#About references to game objects
A mod names models, effects, sounds and other content by name. This page describes how those references are checked and resolved, the placeholders used when a name is missing, and the mod log codes from 620 to 699.
#What a reference is, and the one rule
A reference is a name in a mod that must find something: in the game's files, in the mod's own files, in another
mod it needs, or in something code makes at start (a derived class).
The rule. A reference that does not resolve never stops the game: the mod stays on, the thing it named is replaced by a placeholder of its kind where one exists, and the mod log has one Error entry naming the mod, the file, the line (or JSON pointer), the kind and the name, and what was expected. Texts have no placeholder . A file of the mod the cook cannot make (a model whose image is missing or unreadable, a picture that does not read) is not a placeholder's: LumaLink's check and its pack refuse the mod (L804, the cook's reason); at a start the cook leaves the file out and the mod log has the same L804 Error on the mod (source COOK), the mod's other files apply, and a name of the left-out file then answers as a missing one (a model: the placeholder model, 621).
#The kinds, and who resolves each
| Kind | Where it is written | Resolves against | Checked by |
|---|---|---|---|
| texture of a model | a glTF's images (embedded or a URI inside the mod) | the mod's files | validator, L600-L619 block |
| texture of a material, program of a material | a material source, a shader name | the mod's files, the game's programs, the mod's shaders | validator, L620-L649 |
| texture of a particle; an effect's particles | the effects source | the mod's files, the game's particle textures by name | validator, L650-L669 |
| joint | an effect or socket bound to a joint; a character bound by joint names | the model it is bound to (the game's or the mod's) | validator, L600-L619 and L650-L669 |
| animation | an actor's animation by name | the model's archive | validator, L670-L679 |
| sound | a sound by name | the game's sound table, the mod's sounds | validator, L680-L689 |
| text | a message id (3.8; a placement's message, a layout's text) | the game's message tables in each language, the mod's added lines | validator, L690-L699 |
| object class | a placement row's class name | the game's factory (self-description) and classes mods make | validator (an after_start row for a class no game list names), then the game after the mods' start |
| file | a whole file or patch target (luma.json 5) | the game's store | validator, L302 (exists) |
| a name code passes at run time | assets, draw, audio, LumaKit calls taking a name |
as its kind | the call itself, and the validator for names the compiler lifts |
This contract asks one thing of every such rule: its finding carries kind, found (the name) and expected (where
it was looked for) as parameters, so the game's placeholder step can read from the kept report which names
to replace, without a second check.
#When the game resolves
- At import and at each start: the validator's start check runs every reference rule with the store, the
self-description and the installed mods. The self-description is the
lumafolder beside the game's program (an installed game'sversions/<v>/luma), read as LumaLink's--namesreads it: the function rows,luma_types.json,luma_services.jsonand the placement factssmg_game.luma-placement.json(LumaValidateInputnames,types,services,placement), so the game and LumaLink judge a mod alike. Without the folder (a development build, a device with none) those rules go unchecked; one the validator refuses is said on stderr and the mod is checked as without it. Its findings become mod-log entries (source VALIDATOR, at the title's summary). A start's check reads the kept report for the rules that read the whole.luma; reference rules that read the store or other mods run again at every start, so a game update or another mod's removal that breaks a reference is found then. - After start: object classes. A row of a stage's placement table (
jmp/Placement/<layer>/orjmp/MapParts/<layer>/, not the zone listStageObjInfo; a patch'sadd,rows,setandselect, or a whole table infiles/) names its object's class. A class that neither the game's factory list (the placement facts'factory) nor its planet table names, and that is not made by its shape (ShapeModelNoother than -1), may be one a mod's code makes. The validator keeps it in the mod's report as anafter_startrow (class, file, and the line ofnamein a patch or the row's number from 1 in a whole table) and counts it as not checked (L403,Missing.AfterStart;Missing.Classeswhen the factory list was not given, and then every placement but a planet's waits). After the last mod's start, before any scene, the host gives every mod's rows to the game module'sluma_refs_check_after_start(luma_refs.h), once; the game asks its factory (with every mod's classes) for each. The planet table is a scene's, so planets are the validator's to know: it reads them from the store's table as the mod's own files and patches leave it (a whole table stands for the game's; a patch's rows and values add theirPlanetName), whether or not the factory list is given. A class no mod made isContent.MissingClassin the mod log, and each placement of it makes the placeholder object. - Nothing is resolved lazily for content: by the title every content reference of every mod on is either resolved or has its placeholder decided. A stage loaded later reads the decision, it does not look again.
#Placeholders
The placeholder model is the object archive NebulaPlaceholder (the game's ObjectData/NebulaPlaceholder.arc as
the store has it), cooked from data/placeholder/model.gltf with 3.2's model path; the placeholder object loads it by
that name.
| Kind | Placeholder | Made by |
|---|---|---|
| model (new: an object the game does not have) | nebula:placeholder/model: a 100-unit cube, a magenta and black checker on each face with a white "?" |
the game, when content.model is given a name no store has; a mod file the cook cannot read is refused (L804), not replaced |
| model (replacing one of the game's) | the game's own model | the cooker keeps the game's file and leaves the mod's out (the mod's other files still apply) |
| texture | nebula:placeholder/texture: 64 x 64, magenta and black 8-pixel checker, opaque |
the draw service, for a texture name it does not find; a glTF naming a missing image is refused by the cook (Cook.Material.MissingTexture, L804) |
| material program | the default lit program with the material's base color; never the missing pass | the game, when the program is absent at load (3.13 refuses the start if the compiler itself is absent) |
| particle effect | nebula:placeholder/effect: a slow ring of 8 white and magenta sparks, 50 units across, at the binding point |
the game, when an effect name does not resolve |
| particle texture | the texture placeholder | the cooker |
| joint | the model's root joint | the game, at binding |
| animation | the model's bind pose (a mod's new actor) or the game's own animation of that name (a replacement) | the game, at the animation's start |
| sound | nebula:placeholder/sound: a 120 ms soft two-note chime (NebulaData/PlaceholderSound.nsfx, cooked from data/placeholder/sound.wav), at the call's place and bus |
the audio service, when play, play_at or music is given a name no file has; as music it plays once. A name of the game's own sound table (game_play) not there is answered LUMA_E_NOT_FOUND |
| text | none: a missing message id is not replaced | |
| object class | the placeholder object with nebula:placeholder/model |
the game, after the mods' start |
- The placeholder assets are Nebula's own data: sources under
data/placeholder/in Nebula, cooked into the store with the rest of Nebula's data by the importer. Their absence is a start-up error, so a placeholder can never itself be missing. - A placeholder is drawn, sounded or shown exactly as its kind is; it costs only what the thing it stands for would.
- Each placeholder stands for one reference, and its mod-log entry names that reference. The harness reads
placeholder {"mod", "kind", "found", "file", "line"}facts when one is first used.
#The call
content.model, content.fx, the draw service's textures and the audio service's sounds (play, play_at, music),
given a name they do not find:
- returns the placeholder's handle and
LUMA_OK(the caller's program goes on, the placeholder shows), and - reports through
reportthe content code of its kind,fileandlinethe caller's (LumaScript passes them; a C mod passes__FILE__,__LINE__), once per (mod, file, line, code) asreportalready counts repeats.
#Mod log codes 620 to 699
| Code | Row | English | Args |
|---|---|---|---|
| 620 | Content.MissingClass |
{mod}: {file} places "{found}", which no mod made; a placeholder stands there. |
file, found |
| 621 | Content.MissingModel |
{mod}: there is no model "{found}"; a placeholder is drawn instead. |
found |
| 622 | Content.MissingTexture |
{mod}: there is no texture "{found}"; a checker is drawn instead. |
found |
| 623 | Content.MissingEffect |
{mod}: there is no effect "{found}"; placeholder sparks are shown instead. |
found |
| 624 | Content.MissingSound |
{mod}: there is no sound "{found}"; a chime plays instead. |
found |
| 625 | Content.MissingText |
{mod}: there is no text "{found}". |
found |
| 626 | Content.MissingJoint |
{mod}: {model} has no joint "{found}"; its root is used. |
model, found |
| 627 | Content.MissingAnimation |
{mod}: {model} has no animation "{found}". |
model, found |
| 628 | Content.MissingProgram |
{mod}: the material "{found}" has no program for {renderer}; it is drawn plainly. |
found, renderer |
| 640-669 | Effects | See Adding particle effects. | |
| 670 | Content.EventPastEnd |
{mod}: the event "{found}" of {clip} is at frame {frame}, after its last frame {last}, so it never plays. |
found, clip, frame, last |
| 671 | Content.MissingParam |
{mod}: the material "{material}" of {model} has no shader parameter "{found}". |
model, found, material |
| 672 | Content.MissingFont |
{mod}: the font {found} is not there or cannot be read; the message font is used instead. |
found |
| 673 | Content.MissingMovie |
{mod}: there is no movie "{found}"; nothing is played. |
found |
| 674 | Movie.NoScene |
{mod} called {where} while no stage with a movie player was running; it did nothing. |
where |
| 675 | Movie.NotMovie |
{mod}: {where} was given "{found}", which is not a cooked movie; nothing is played. |
where, found |
| 676-699 | free for 3.2 to 3.13 |
#No mod, no cost
No mod: no reference is read, no placeholder loaded (they are in the store, read only when used),
luma_refs_check_after_start is not called.