#About the detailed rules
This page holds the detailed rules of LumaScript that complete the other reference pages: the grammar, operators, conversions, json, flow checks, wait, defer, and how the compiler reads services from their headers.
#More types and calls
if let: takes the same list asguard:if let r = room, not r.host, let p = r.peers.get { }checks each in order; the names bound are in scope in theifblock only.- container functions (each a compile error on the wrong type, never a run-time lookup):
list<T>:len -> int,push(T),pop -> T?,insert(int, T),remove(int) -> T(out of range: a script error),get(int) -> T?,[int](out of range: a script error),contains(T) -> bool(T with==),indexed -> list<(int, T)>,map(fn(T) -> U) -> list<U>,filter(fn(T) -> bool) -> list<T>,any(fn(T) -> bool) -> bool,all(fn(T) -> bool) -> bool,sum(fn(T) -> N) -> N(N a number type),sort(T with<),sort_by(fn(T, T) -> bool),first -> T?,last -> T?.map<K, V>:len,get(K) -> V?,[K](read: a missing key is a script error; write: adds or replaces),contains(K),remove(K) -> V?,keys -> list<K>,values -> list<V>(both in key order: integers and enums by value,textby bytes, so the same on every platform);for (k, v) in m.set<T>:len,add(T) -> bool,remove(T) -> bool,contains(T),values -> list<T>(in order).text:len(bytes),chars,split(text) -> list<text>,starts_with,ends_with,find(text) -> int?,slice(int, int)(byte offsets on code point boundaries, else a script error),lower,upper(Unicode simple case mapping),parse_int -> i64?,parse_float -> f64?.bytes:len,[int],slice,push(u8),read_u16/u32/u64/f32/f64(at, big: bool),write_u16/...(at, value, big: bool)(out of range: a script error).
- nerves by name:
nerve "DinoPackunVs1.BattleLv2"is the game'sconst Nerve *for that class's step, usable where a game function takesconst Nerve *(self.setNerve(nerve "...")) and comparable withsame(...)togetCurrentNerve. Checked at compile time against the self-description's list of each class's nerves; a name not listed is a compile error naming the class and its nerves. A nerve named by a run-timetextis not possible (no run-time lookup): a nerve chosen while running is amatchover the class's steps, which the mod's build can generate from the same list. wrap ... every override of:wrap every override of LiveActor::movement { ... }ashookallows (K.vhook);selfis the object, of the virtual's class.- a hook calling the function it hooks: inside any hook of a mod, a call to a function the same mod
hooks runs the other mods' hooks and the game's code, not this mod's hooks on it (no recursion through one's own
hooks); another mod's hooks run as usual (an
after MR::getPlayerPosthat callsMR::getPlayerPosgets the value without its own hook). result =for a function returning a pointer to a vector (Vec3f *,const TVec3f &): the value is kept in a slot of that hook (one per hook, on the game thread) and the caller receives a pointer to the slot, valid until the hook next runs. A caller that keeps the pointer across a second call of the same function sees the newer value; the compiler warns (S-code) on every such hook, naming the function.- The self-description's nerves come from the game source's
NEW_NERVEandNEW_NERVE_ONENDdeclarations (3,434 and 161 of them):NEW_NERVE(BossKameckVs1NrvBattleLv2, BossKameckVs1, BattleLv2)isnerve "BossKameckVs1.BattleLv2", with its address per build.
The rules below refine the sections above; the grammar (Appendix G) is executable.
#Words
- Reserved (never a name of the mod's own):
use pub let var fn return if else while for in break continue match struct enum class override hook wrap replace proceed skip state states go wait task stop on option true false none self result as and or not extern export defer test expect guard start log ref.constandisare gone. - Contextual (a word only where the grammar places it, a name everywhere else):
before after every override of until frames seconds fact optional enter update exit game c draw layers stage frame load, and the content wordsmodel effect sound layout text font movie data nerve(a content literal only when a string follows). - After
::or.any word is a name:GameScene::start,GameScene::update,x.frames,p.0. - A
usepath's parts are words, reserved ones included (use kit.player.state,use ./player/state). The module's name is its last part (unlessas), and a reserved word right before.in an expression names that module (state.enter(...)). - The game's statics are written as the game names them,
GameSystem::sInstancesogamenames nothing of the language anduse svc.save.gamenames the service.
#Lines
A line end ends a statement, a field, a case, an entry or a match arm. It does not when: it is inside `` or [ ]
(but inside a { } within them it does again); the line ends with an operator, ,, :, ->, => or an open
bracket; or the next line starts with else (except else =>, a match arm). Inside { } of a literal, a struct, an
enum or a match, entries are separated by , or a line end, either or both. After a statement that ends with a
block's }, the next statement may follow on the same line (enter { ... } wait 180 frames).
#Hooks: re-entry, replace's error path, threads, order
- The hook flag is cleared around
core->proceed(call)and set again after it , so a recursive game function, or an override that calls its base underevery override of, runs every mod's hooks each time, as the game would. - A
replacewhose body ends in a script error gives the game's own result bycore->proceed(call)(which runs the wraps after it and then the function), not byinvoke(which would enter the function from the top and run every hook twice). - Every script hook, task and handler runs on the game thread only. The generated code tests it first; a call on
another thread does nothing (a
beforedoes not skip, awrapproceeds, anafterleaves the result) and logs once per hookS0901: <function> called off the game thread: the hook is left out there. The self-description marks functions known to run off the game thread (the self-description); hooking one is a build warning naming it. - Between mods: the mod higher in the list is outermost: its
beforeruns first, itsafterlast (its result stands), itswrapencloses the lower mods' wraps.
#Handles across a stage change
6.2's last paragraph reads: an object goes in one of two ways, and a handle learns both: one by one, through the
destructor rows of its class (LUMA_TELL on NameObj::~NameObj and its overrides); and all at once when a stage's
arena is released (NebulaArena::destroy runs no destructor for most actors): the kernel tells the mod the
released address range and lumart empties every handle whose object lies in it. A test: a
ref<Kuribo> kept in a module var across a stage change gives none. ref<C> takes only a class derived
from NameObj (or one the self-description marks with a lifetime); anything else is a compile error naming it.
#Operators and precedence
Loosest first: ?? (right to left); or; and; not (prefix); comparisons == != < <= > >= (one per expression:
a == b == c is an error); .. ..=; |; ^; &; << >>; + -; * / %; prefix -, wait, start; as
(binds tighter than every binary operator: a as u32 * b as u32 is (a as u32) * (b as u32)); postfix: a call
(...), [i], .name, ?.name, and ! ("the value, which must not be none", a script error when it
is). There is no prefix ! and no &&, ||, ? :. x == none and x != none test any T? (T need not have
==).
#Calls: named arguments
A call gives its positional arguments first, then any by name, name: value: draw.tint(a, multiply: #FFFFFF, add: c). A name the function lacks, a parameter given twice, or a required one missing is a compile error naming it.
Named arguments are for the mod's functions, LumaKit's and services' (whose parameters have names); a game function
takes positional ones only (the self-description may not name its parameters). An enum case with fields is
constructed as a call, actor.Sensor.Body(radius: 70.0), positional or named by its fields. A var argument is
written var x.
#Null game pointers
Every game pointer or reference result, every pointer field read from a game object, and every pointer
parameter is T? (and const char * is text?), unless the self-description marks it never-null. The self-description takes
that mark only from evidence: a C++ reference type T &, or a list kept by hand with each row's reason. So
MarioAccess::getPlayerActor is MarioActor? (if let p = MarioAccess::getPlayerActor { ... }), and none
may be passed for a pointer parameter (initModelManagerWithAnm("Crumble", none, false)). self in a hook or a class
is never none.
#Hook heads
The function is named Class::name, by backquotes (`MR::isNear(const LiveActor *, f32)`), or as either followed
by its parameters: names only ((actor, at, dist)), or names with LumaScript types (MR::isInWater(at: vec3)), which
choose the overload whose parameters map to those types (none or two: a compile error listing the signatures). -> name names the result in an after; -> type gives the result's type in a before that may skip with a value.
#Module level
A module holds only declarations: use, option, let, var, fn, struct, enum, class, task, hooks,
on, states, test, extern, export. A module let or var may be any expression; they run when the mod
starts, in module order, before every on start (as abi 8 already says); one that reads the game runs after every
import is bound. const is withdrawn: a module let is the one way (the compiler folds it when it is constant).
A bare statement at module level is an error (on start { } holds it).
#Literals
[a, b]a list;{}an empty map or set, by its place;{k: v, ...}a map;{a, b}a set;Name { field: v, shorthand }a struct (a capitalized name, or a module's:item.Item { ... }), fields by,or line ends.- A struct literal is not allowed directly in the condition of
if,while,match,guardorfor ... in(it would read as the block); put it in parentheses. json.Value: a literal (list, map, text, number, bool,none) in a place that takes ajson.Valuebecomes one, each value by its kind, recursively; a map's keys aretext.json.Valuehas.text .int .float .bool .list .map(eachT?) and.get(text) -> Value?,.at(int) -> Value?.
#Conversions
wrap(...) as a conversion is withdrawn: wrap is the hook form only. Keeping an integer's low bits is
low_bits<T>(n). Built-ins that take a type (json.decode<T>, low_bits<T>) write it in < > right before the
call's (; that is the only place a type follows an expression (user generics stay out; see Not in LumaScript).
u32.max, i16.min... are each integer type's limits.
#Options
option <key>: <type> declares an option of luma.json's options by its key; the types match its kind: toggle
-> bool; number -> int when its default, min, max and step are whole, else f32 (declaring int for a
number with a fraction is an error naming it); text -> text; choice -> text (one of its values, which a
match on it may list); key -> input.Action. An option is read by its key as a name (balls_at_once); there is
no option("key") call.
#Smaller words
- One container way each:
filter(noretain:balls = balls.filter(...)),set.add(noinsert),filter(...) .last(nolast_where). A handle is empty whenh.get == none(noempty). map[K]givesV(a missing key is a script error);map.get(K)givesV?.same(a, b)for views and service handles (nosame_stream).selfis the first parameter of a struct's function or a class member only; a free function names its own.matcharms may be integer, text or bool literals, a negative number, an enum case (E.Case(x),E.Case { a }) or a tuple of patterns;else =>for the rest (no_ =>). An arm's body is a statement or a block.- A closure's parameters are typed; its result type may be left out when it gives none (
fn(i: int) { ... }).
#pending<T> and text with placeholders
- A call that answers later (a service request such as
fs.read, or LumaKit'sscreen.choose,talk.askandcutscene.play) returnspending<T>. Onlywaitreads one, andwaitis allowed only in atask, a state's body orenter, or await-holding handler that the compiler makes a task (on startand events): in afnor a hook it is an error naming the line (a function that waits is atask). Apendingdropped withoutwaitis a warning. text "Key"is the mod's text row in the player's language. Its placeholders{name}are filled by named arguments right after it:text "Coop.Hosting"(address: outside). Each placeholder of the row must be given (in every language's row), and no other: checked when building, as content names are.- Content literals take a plain string (no
{...}): content is named when building (nerve "{a}.{b}"is an error).
#Grammar
(* G.1 tokens *)
IDENT = letter_or_ "_" { letter | digit | "_" } ; (* not a reserved word *)
GAME = "`" { any but "`" and line end } "`" ;
NUMBER = "0x" hex {hex|"_"} | "0b" bin {bin|"_"} | digit {digit|"_"} ["." digit {digit|"_"}] [exp] [suffix] ;
COLOR = "#" hex*6 [hex*2] ;
STRING = ["r"|"b"] '"' { char | "{{" | "{" expr "}" } '"' ; (* "{...}" interpolates; not in r or b strings *)
comments = "//" ... line end | "/*" ... "*/" (nesting) ;
END = line end | ";" ;
(* G.2 module *)
module = { item END } ;
item = use | option | ["pub"] ( binding | fn | struct | enum | class | task ) | hook | on | states | test
| extern | export ;
use = "use" ( "c" STRING | ["optional"] ( "." "/" WORD { "/" WORD } | WORD { "." WORD } )
[ "." "{" IDENT { "," IDENT } "}" ] [ "as" IDENT ] ) ;
option = "option" IDENT ":" type ;
binding = "let" pattern [":" type] "=" expr | "var" IDENT ( ":" type ["=" expr] | "=" expr ) ;
fn = "fn" IDENT params ["->" type] block ;
params = "(" [ param { "," param } ] ")" ;
param = ["var"] ( "self" | IDENT ":" type ["=" expr] ) ; (* self: first, in a struct or class only *)
struct = ["c"] "struct" IDENT "{" { ( IDENT ":" type ["=" expr] | fn ) SEP } "}" ;
enum = "enum" IDENT "{" { IDENT [ ("(" | "{") { IDENT ":" type SEP } (")" | "}") ] SEP } "}" ;
class = "class" IDENT ":" gname "{" { ( binding | "override" "fn" IDENT lparams ["->" type] block | fn | hook ) END } "}" ;
task = "task" IDENT params block ;
hook = ( "hook" ("before" | "after") | "wrap" | "replace" ) ["every" "override" "of"] gname [lparams]
[ "->" ( IDENT | type ) ] block ; (* -> IDENT names an after's result *)
lparams = "(" [ IDENT [":" type] { "," IDENT [":" type] } ] ")" ;
gname = GAME | IDENT { "::" ["~"] WORD } ; (* WORD: any word, reserved or not *)
on = "on" ( "start" | "stop" | "frame" | "load" | "option" IDENT | "stage" STRING | "draw" dotted
| "layers" "->" type | dotted [ "(" [ IDENT { "," IDENT } ] ")" ] ) block ;
states = "states" IDENT "for" IDENT "{" { ( "state" IDENT "{" { ( ("enter"|"update"|"exit") block | stmt ) END } "}"
| "start" IDENT ) END } "}" ; (* exactly one start *)
test = "test" ["game"] STRING block ;
extern = "extern" "c" "fn" IDENT params ["->" type] ;
export = "export" "c" "fn" IDENT params ["->" type] block ;
SEP = { "," | END } ; (* at least one between entries *)
(* G.3 types *)
type = ( "(" type { "," type } ")" | "fn" "(" [ type { "," type } ] ")" ["->" type] | "ref" targs
| ( GAME | IDENT { ("." | "::") IDENT } ) [targs] ) { "?" } ;
targs = "<" type { "," type } ">" ;
(* G.4 expressions, loosest first *)
expr = coalesce ;
coalesce = or_ [ "??" coalesce ] ;
or_ = and_ { "or" and_ } ;
and_ = not_ { "and" not_ } ;
not_ = "not" not_ | compare ;
compare = range [ ("==" | "!=" | "<" | "<=" | ">" | ">=") range ] ;
range = bor { (".." | "..=") bor } ;
bor = bxor { "|" bxor } ; bxor = band { "^" band } ; band = shift { "&" shift } ;
shift = sum { ("<<" | ">>") sum } ; sum = product { ("+" | "-") product } ;
product = unary { ("*" | "/" | "%") unary } ;
unary = "-" unary | "wait" ( "until" expr | unary [ "frames" | "seconds" ] ) | "start" postfix
| postfix { "as" type } ;
postfix = primary { args | "[" expr "]" | ("." | "?.") WORD [targs] | "!" } ; (* targs only before "(" *)
args = "(" [ arg { "," arg } ] ")" ; arg = ["var"] expr | IDENT ":" expr ; (* positional first *)
primary = NUMBER | COLOR | STRING | "true" | "false" | "none" | "self" | "result" | "proceed" "(" ")"
| "ref" args | if | match | "fn" params ["->" type] block | "(" expr { "," expr } ")"
| "[" [ expr { "," expr } ] "]" | "{" { expr [":" expr] SEP } "}"
| CONTENT STRING [args] (* plain STRING; args for "text" only *)
| GAME | IDENT { "::" ["~"] WORD } | IDENT [targs] | dotted "{" { IDENT [":" expr] SEP } "}" ;
(* struct literal: capitalized last name; not in a condition *)
dotted = IDENT { "." IDENT } ;
CONTENT = "model" | "effect" | "sound" | "layout" | "text" | "font" | "movie" | "data" | "nerve" ;
(* G.5 statements *)
block = "{" { stmt END } "}" ; (* after a "}" the next stmt may follow on the line *)
stmt = binding | fn | "return" [expr] | "break" | "continue" | "stop" | "skip" [expr] | "go" dotted
| "defer" stmt | "log" ["fact" expr] expr | "expect" expr | "guard" conds "else" block
| "while" cond_expr block | "for" pattern "in" cond_expr block | expr [ assignop expr ] ;
if = "if" conds block { "else" "if" conds block } [ "else" block ] ;
conds = cond { "," cond } ; cond = ["let" pattern "="] cond_expr ; (* cond_expr: no struct literal *)
match = "match" cond_expr "{" { ( "else" | pattern ) "=>" ( block | stmt ) SEP } "}" ;
pattern = "(" pattern { "," pattern } ")" | NUMBER | "-" NUMBER | STRING | COLOR | "true" | "false" | "none"
| dotted [ "(" [ pattern { "," pattern } ] ")" | "{" [ IDENT { "," IDENT } ] "}" ] ;
assignop = "=" | "+=" | "-=" | "*=" | "/=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>=" ;#A replace off the game thread
A call on another thread runs no script hook. A before does not skip, a wrap proceeds, an
after leaves the result, and a replace proceeds: the game's own function runs and its result stands. Each is
logged once per hook as S0901.
#Match patterns
A match arm's pattern names an enum case written with its enum: Shape.Ball(r), Shape.Box { w, h },
(Shape.Dot, 0). A bare name at the arm, or as an element of the arm's tuple, is an error. It would match every
value, so a misspelt case would quietly take everything: "an enum case written with its enum (E.Case), a literal
or else". Inside a case's fields a bare name binds the field (Shape.Ball(r)). _ is not a name anywhere
(arms, let, parameters); the rest of a match is else =>. let, if let and for patterns take names as before.
#Options: which values decide int or f32
A number option is int when its default (always present, luma.json) and those of min, max and step
that are present are all whole; an absent one does not count. Otherwise it is f32.
#A struct literal in a condition
A struct literal cannot start a condition: if Point { x: 1 } == p is refused at the { with "no struct literal in
the condition of if, while, match, guard or for: put it in parentheses". (A { after a capitalised name
whose next words are name: cannot open a block, since no statement starts so.) The parser likewise names the word
for && (and), || (or) and a prefix ! (not).
#What may be none, by evidence, both ways
- Results and fields are
T?unless the self-description marks them never-null. - Parameters change. A pointer parameter takes
T, notT?, unless the self-description marks it may-be-null. It marks it only from evidence:- the function tests it (
if (p),p != nullptr,p == nullptrbefore any use); - or it passes it only to a parameter that is itself may-be-null, followed through the calls;
- or a hand-kept list row gives the reason.
Passing
none, or aT?, to aTparameter is a compile error naming the function and the parameter: "test it first (if let) or give a value". Avar xargument is never null. Rows with their evidence: LiveActor::initModelManagerWithAnm2nd: LiveActor.cpp:382 and 384 test it, and ModelManager.cpp:437.MR::calcGravityVector(const LiveActor *, ...)3rd: through calcGravityVectorOrZero to PlanetGravityManager::calcTotalGravityVector, which tests it at :21. 4th: GravityUtil.cpp:45 tests it.MR::getFirstPolyOnLineToMap1st and 2nd: getFirstPolyOnLineCategory tests both (MapUtil.cpp:79 and 83).
- the function tests it (
- Text with a
T?. Interpolating aT?("{x}") is a compile error: "xmay be none: write{x ?? ...}or test it withif let". AT?given where aTgoes is the same error, for the mod's own functions as for the game's. - Never-null by evidence, for the self-description's hand list:
MR::getCurrentStageNamegivesmCurrSceneControlInfo.mStage, which is""from SceneControlInfo's constructor (GameSystemSceneController.cpp:50). It is written only withMR::internName's result (:57, :460 from the next info, :466""), and internName maps null to""(StringUtil.cpp:480). So it istext. - A result that is a field's address of another result.
MR::getPlayerPosis&MarioAccess::getPlayerActor->mPosition(PlayerUtil.cpp:70). With no player it is not null but an address near 0, so neitherTnorT?makes it safe. The self-description marks such a function needs the inner one:- when the body dereferences or offsets a may-be-null result with no test, the row says
needs MarioAccess::getPlayerActor; - the generated call tests the needed function first and gives
nonefor aT?result. For a function with no result or a value result it gives a script error naming the need, and the game's function is not called. - The player rows are the first evidence: getPlayerPos, getPlayerCenterPos, getPlayerRotate, getPlayerShadowRotate, getPlayerGravity, getPlayerUp/Front/SideVec, getPlayerGroundPos, getPlayerHitRadius, isPlayerInAreaObj (PlayerUtil.cpp:66 to 154).
- So
MR::getPlayerPosisvec3?.
- when the body dereferences or offsets a may-be-null result with no test, the row says
#Nested wraps
Under every override of, a base's wrap runs inside its override's. A wrap that sets module state
around proceed saves and restores it: let was = current; current = self; proceed; current = was, never
current = none after.
In an
after,-> IDENTright before the block names the result (-> n {,-> bool {too: an after's result type is the game's). Anything else after->is a type.on draw <dotted>takes any dotted point (d.Point.Hudafteruse draw as d).on <word>.<...>is always an event path, whatever the word (on stage.entered,on frame.x): start, stop, frame, load, stage, layers and draw are the event words only when no.follows.log fact:factis the word when a value starts right after it (a string, a number, a name, a color, a game name, true, false, none, self, result).log fact + 1andlog fact.nlog a variable named fact.No comma before the
)or]of a comma list (parameters, arguments, lists, tuples, fn types, patterns, event names). Brace lists (SEP) may end with,or a line end.Only a block's
}lets the next statement follow on the same line. After a struct literal's, a map's, a match's or a declaration's}the next statement needs a line end or;.lparams(a hook's or an override's) is names, each with an optional type:varand defaults are errors.usetakes.{names}after a local path too, andasafter any form.After type arguments, a token that starts with
>gives up its first>:list<int>= [],map<text, list<int>>= {}.One
startline perstates; a second is S0020 at the second.A program nests at most 512 levels deep (
MAX_DEPTH). Each of these is one level: a bracket, a block, a type inside a type, a pattern inside a pattern,not, a prefix-,wait's amount,defer's statement, a value in an interpolation, and each node an operator or a postfix wraps around what came before (a + b + cis two deep,ftwo,x as A as Btwo). Past it is S0022 at the place, and the parse goes on. The compiler works on a stack of its own (64 MB), so any program within the limit is read in any build.A line end after
>or>>is not dropped by the lexer, so a type ending in them ends its line (items: list<int>,target: ref<Actor>,var m: map<text, list<int>>). As operators they still go on to the next line (a >/bis one comparison,a >>/bone shift): the parser skips the line end after them.An interpolation, and a string inside one, ends on its line; one that does not is S0004 at its
{.One leading UTF-8 byte-order mark is skipped; CR LF and a lone CR each end a line.
A word with a letter outside ASCII (
café) is S0023, said once for the whole word, which reads on as a name.Build-time codes S0001 to S0024 (S0022 the limit, S0023 names, S0024 the compiler could not start its thread) are worded in LumaLink's rows
LumaLink.Script.*in the 14 languages; codes from S0901 are the run time's. Of two diagnostics at one place only the first is said.Type arguments take their
(on the same line:json.decode<list<int>>/(data)is S0025 (below).
#Type arguments at a line end
- A call's type arguments that end a line, with its
(at the start of the next (json.decode<list<int>>/(data)), are S0025 at the(, said once; the compiler reads on as the call. Such text was an error already (as written it is no call, and its comparison reading is a chained comparison, S0013). A comparison whose>>ends a line still goes on as a shift (a < b >>/(c)isa < (b >> (c))).
#What the checker reads
Each item is what the checker (crates/lumascript, check/body*) does, tested in tests/body.rs; codes S0047 to S0100 are worded in LumaLink's rows in the 14 languages.
#Strings
- Escapes (S0093 names any other, with what follows the
\):\n \t \r \0 \\ \" \' \{ \};\xHH(two hex digits: below 80 in text, any byte inb"...");\u{H}to\u{HHHHHH}(one to six hex digits, a Unicode scalar value, not a surrogate). A raw string has none. The lexer reads\u{...}whole, so its{opens no interpolation (as\{does not). - Text is joined by interpolation (
"{a}{b}"), not by+. A value put in text (an interpolation,log) is a number,bool,text,json.Value, a vector,quat,color,mat34, an enum of the mod or the game, or a list, set, map or tuple of those; aT?is S0067 (test it or give a value with??); anything else S0080. t.bytesgives a text's UTF-8 asbytes.
#Operators
| Operator | Takes | Gives |
|---|---|---|
+ - * / % |
two numbers of one type | that type |
+ - |
two vectors of one size | that vector |
* / |
a vector and f32 (f32 * v too, for *) |
the vector |
+ |
two colors | color |
* |
color and f32 |
color |
& | ^ |
two integers of one type | that type |
<< >> |
an integer, shifted by any integer | the left side's type |
== != |
two of one type that compares (below) | bool |
< <= > >= |
two numbers of one type, or two texts | bool |
.. ..= |
two integers of one type | a range |
and or not |
bool |
bool |
?? |
a T? and a T (or a T?) |
T (or T?) |
- A literal side takes the other side's type (
x + 1withx: u8isu8;1.5 * visf32 * vec3); two literals areint, orf32when either is a float. A mismatch is S0065, a wrong single side S0066, said once. - What compares (
==,!=, a list'scontains): every type but functions, views, game arrays, service handles, classes, tasks, pending results and content names; a list, set, optional, map or tuple when what it holds compares; a struct or enum of the mod when each field it holds compares (one that holds itself through a list compares by its other fields). Views and service handles:same(a, b)(S0073 says so). x == noneandx != nonetake anyT?; on a value that is never none, S0086.
#Built-in calls
| Call | Takes | Gives |
|---|---|---|
min max clamp |
numbers of one type | that type |
abs |
a signed integer or a float | that type |
sqrt sin cos, atan2 |
floats of one type (literals: f32) |
that type |
lerp(a, b, t) |
two floats, vectors or colors of one type, and t (f32, or the floats' type) |
the type of a |
dot length |
vectors of one size | f32 |
cross |
two vec3 |
vec3 |
normal |
a vector | that vector |
hash32(t) |
text |
u32 |
low_bits<T>(n) |
an integer type T, any integer n |
T |
vec2 vec3 vec4 quat |
2, 3, 4, 4 f32 |
the value |
color(r, g, b), color(r, g, b, a) |
f32 0..1 each |
color |
same(a, b) |
two views of related records, the mod's object and a view of its base, a nerve and the game's const Nerve *, two handles of one service type (each may be T?) |
bool |
Built-in names take positional arguments only. json alone is no value (S0083).
#json
json data is:
bool, a number,text,json.Value, a vector,quat,color,mat34, a game enum; a list, set, optional or tuple of json data; a map whose keys aretext, an integer,boolor an enum and whose values are json data; a struct or enum of the mod whose fields are json data. A game struct by value is not (its fields may be pointers: copy what is wanted into a struct of the mod). Views,refs, functions,bytes, tasks, pending results, classes and service handles are not either (S0094).How it is written (4.3 and lumart follow this;
json.decodereads the same back):Value json bool, a number,texttrue/false, a number (integers exactly, past 2^53 too), a stringnonenullvec2 vec3 vec4 quat[x, y],[x, y, z],[x, y, z, w],[x, y, z, w]color[r, g, b, a], each 0..1mat34[[...], [...], [...]], its three rows of foura list, set or tuple an array a map an object; an integer key in decimal, boolas"true"/"false", an enum's by its namea struct of the mod an object of its fields by name an enum's case without fields its name, a string ( "Walk")an enum's case with fields {"Case": {fields by name}}a game enum its value's name (the first declared, for values with two) A float that is NaN or infinite is a script error when written (json has none). Reading, an object's extra keys are skipped, and a missing field takes its default, else the whole decode is
none.A literal in a place that takes a
json.Valuebecomes one; inside it, a value that is no literal must be json data, as above.json.encode(x)takes json data (a written list or map literal is read as ajson.Value) and givestext.json.decode<T>(data)takestextorbytesand givesT?(nonewhen the data does not read as aT);Tis json data.A
json.Value's.intisint?(i32) and.floatisf32?:nonewhen the value is no number or does not fit (an integer pasti32, a fraction for.int)..text .bool .list .map .get(k) .at(i)work the same way.
#Calls
- A named argument may be a
varone:name: var x. - A game function is chosen from its signatures so: those that take the arguments (S0058 lists them when none does);
among several, those each argument fits as it is: an integer literal is exact for
i32only and a float literal forf32only, as C++ picks (pickwithpick(s32)andpick(u32)iss32); among several still, on a const view the const member. More than one left is S0059, naming them, and backquotes choose. - Members and statics (
luma_functions.json): a member function is called on an object (actor.appear), or by its full name onselfinside a class or hook of its record (LiveActor::appearin a class derived from LiveActor); elsewhere it is S0100. A static or free function takes no object. Without the facts file, S0033 is said once per name and calls are read as written. - A signature none of whose forms crosses (variadic, unreadable) is S0090; one whose parameter or result does not cross is S0060 or S0061 with the reason.
- A pointer to a number, vector or enum as a parameter does not cross;
T ¬ const is avarparameter, writtenvar x(S0062, S0063). - A game function that takes a record by pointer or reference is given the game's object (a view), never the script's
own copy of a plain game struct (
let b = a.mBoxcopies it): S0098.MR::useBox(a.mBox)passes the game's object.
#as
as converts a number to a number, a game enum to an integer and an integer to a game enum, and an enum of the mod
without data to an integer. Nothing else (S0069).
#The game's enums
- A value is written
Mode::Walkin an expression (an unscoped enum's also by its scope and value alone,Walkat global scope); a value of an unnamed enum is anint. - In a
matcharm it is written dotted,Mode.Walk(patterns have no::; the checker joins the path with::), and S0068 names missing values that way. Two names of one value are one case, so an arm for each value is a completematch. asconverts a game enum to an integer and back.
#Places
A write (=, +=, a var argument) goes to: a var local; a field, component (v.x), tuple part or element
(list, map, bytes) of a place; a field of the mod's class object; in a struct's function, a part of self when
it is var self, and in a class or hook a member of self; a game field, global or array element that is not
const, reached through a view that is not const; an after hook's result. S0064 says why anything else is not: a
let, a parameter that is not var, an option, a value (a call's result, a literal, self itself), const in the
game, a const view, or a name a function value captured.
- Literals: an expression of
literals only (
1 + 2,1 << 4,(1 << 4) - 17) takes its place's number type, an integer one also a float place; with no number place it isint, orf32when a literal in it is a float. An integer expression's value is worked out and checked to fit once, for the whole (let x: u8 = 200 + 100is S0050 naming 300). A shift's literal left side takes the place's integer type, elseint, never the count's:1 << nwithn: u8is anint. - Const members: among several still, the member whose const matches the view's: the const one on a const view, the other on a view that is not const.
- Float literals: a float literal is exact
for
f32only. A float literal is anf32, which fits the game, whose float functions takef32; C++ would pickdouble.
#Flow, as the checker reads it
These rules describe exactly what the checker verifies about control flow.
#Returns and guard
- A function, a struct's or class's function, an export, a closure or a local
fnwith a result, and anon layershandler, must not reach its closing}. Every path ends inreturn value, or in a statement that never ends:while truethat nobreakof its own leaves (abreakof a loop inside it does not count). Aniformatchleaves only when all of its branches do, and anifwithoutelsenever does. The error is said at the closing}and names the result type: S0101. guard'selseblock must leave byreturn,stop,break,continue,goorskip, or by aniformatchwhose every branch leaves: S0102, said at theelseblock's{.- Hooks: a
wrapthat proceeds, and abeforethat skips, are its rules.
#Views
A view, which is a value of a game class, a game array or place, a class's object or a field group, is kept past its statement in these places, and only these. Each is S0103, naming the name and where:
- a module value (
letorvarat module level):Script.Keep.Module; - a field of a struct, of an enum's case or of a class:
Script.Keep.Field; - a task's parameter, because a task runs on later frames than the statement that starts it:
Script.Keep.Task; - a closure that may run later, when it reads a local view of the body around it,
self, or a member throughself:Script.Keep.Closure. A closure written directly as a built-in's closure argument (filter,map,any,all,sum,sort_by) runs at once, inside its statement, and may read them. A closure inside such a closure that may itself run later may not. - a local of a state's body read in its
updateorexit, which run on later frames:Script.Keep.State.
The rule follows the type through ?, tuples, lists, sets and maps. A local list of views lives as long as a local
view, so it is allowed. It is refused wherever the view itself would be. This replaces 6.1's "a container", which
read as any container.
A plain game struct (no vtable, crossing by value) read through a view is the script's copy, and also through ?.
(let b = a?.mBox is Box?, a copy). It is no view.
The way to keep an object is a handle: ref(x), then h.get, which gives none once the object is gone.
#wait
- Where.
waitmay be in atask; in a state's body or itsenter; inon start,on stage,on optionoron <service>.<event>, which the compiler makes tasks when they wait; and in atest game. It may not be in afn, a hook, a closure, a state'supdateorexit,on stop,on frame,on load,on draw,on layers, or a plaintest. That is S0105 withScript.Wait.Where. - Where in a statement. A
waitis the first thing its statement reads, so nothing of the statement is held across it. It can be the whole of an expression statement, of alet's orvar's value, of an assignment's value (=), or of a condition ofiforguard. It can also be what those read first:wait p ?? "",(wait p).name,wait p as int,not wait p,(wait p).f(x). Anywhere else (1 + wait p,f(wait p),x += wait p) it is S0105 withScript.Wait.Inside. The fix is aletof its own. - Views across it. A local view made before a
waitand read after it is S0104, naming the local and the wait's line, said once per local. These count as read after the wait:- a read the next time round a loop that waits;
wait until's condition, which is read on each frame after the wait starts;- the local a
forgoes on through when its body waits; - the local whose view an assignment writes through (
a.x = wait p), since the place is written after the wait. A task's ownselfdoes not exist. A state'sselfis its object, which the machine lives with, so it may be read after a wait.
#defer
What defer runs must end where it started. It may not contain return, stop, go, skip, wait, or a break
or continue of a loop outside it. A loop inside the deferred statement may break. Each of these is S0106, naming
the word.
#The time service in LumaScript
#use svc.time: the table as it is
- The functions are the header's, by their names, with
modgiven by the compiler:time.now -> time.Now,time.monotonic_ns -> i64,time.wall -> time.Wall,time.set_rate(rate: u32),time.hold,time.release,time.step(count: u32) -> bool,time.timer(clock: time.Clock, after: u64, every: u64, fn(count: u32)) -> time.Timer?,time.cancel(timer: time.Timer). No property or other sugar: the docs show one list, the header's. - What the C results become:
set_rate,hold,releaseandcancelreturn nothing (a mistake is reported by the service to the mod log, registry 7);stepis false for LUMA_E_BUSY (another mod holds too, or loading: an answer, not a mistake) and true for LUMA_OK;timerisnonewhen it was refused (reported).nowandwallcannot fail. - A service's struct
Luma<Service><Name>is<service>.<Name>(time.Now,time.Wall), its enums likewise (time.Clock.Frames,.Steps,.Nanoseconds; the state'stime.State); a handle is<service>.<Name>of the kind it opens (time.Timer). The leadingsizefield andreservedfields are not the script's: the compiler setssizeto the struct of the minor the mod imports and zeroesreserved. This rule is for every service. time.on_frameandtime.on_stepare not names of the script:on frameandon stepare. Writing them is S0108 withScript.Svc.Handler({name} is set by "on {what}", not called).
#on frame and on step
on frame { }stays lumart's frame pass: at the frame's start in list order, before the mod's tasks . It runs while the world is held. One per module: the mod's one frame pass calls each module's in module list order.on startandon stopare one per module the same way (starts in module order, stops in reverse), as is LumaKit'son mods.stopped.on step { }andon step(now: time.Now) { }are new: one per mod, compiled ontotime.on_step, run once per world step before the scene's update, so 0 times in a held frame and up to 16 in a fast one.nowis the handler's own: itsstepandstep_in_frameare this step's. A secondon stepin a mod is S0109 (Script.On.Twice:a second "on {what}"; the first is at line {line}), as is a secondon loadoron layersin a mod, and a secondon frame,on start,on stoporon mods.stoppedin one module.on mods.stopped(gone)with its parameter untyped oru64is always the LumaKit rule for stopped mods (a mod that called this library's exports is gone); svc.mods' STOPPED event ison mods.stopped(e: mods.StoppedEvent), its record type written.on stepmay not wait (S0105Script.Wait.Where), and it is never a task. It may start one.
#wait N frames and wait N seconds
wait N framescounts frames presented: it goes on while the world is held.wait 0 framesresumes at the next frame's pass.wait N secondscounts world steps at 60 a second: ceil(N × 60) steps, N anintorf32of at least 0. It follows the world's rate and stops while the world is held, as "game time; paused when the game pauses" said. A real-time wait iswait until time.monotonic_ns >= end.- How lumart does it: in its frame pass it reads
time.nowonce; a frames wait resumes whenframereaches its end, a seconds wait whenstepdoes. No timer is opened for a wait, so the service's 64 timers a mod are the script's own (time.timer). A mod whose code waits importstime1.0 (the compiler adds the import; it needs no permission). - After an
after/everyof other languages, LumaScript's way is a task:task t { wait 2 seconds; ... }, a loop forevery.
#on time.timer is refused
Registry 2's event naming makes on time.timer(...) a path, but a timer's events go to the function given to
time.timer, not to a mod-wide handler. on <service>.<event> for an event that has a per-request function is S0107
with Script.On.PerRequest ({event}'s events go to the function given to {call}; it is not an "on" event). time's
timer is the first.
#Codes
S0107 Script.On.PerRequest, S0108 Script.Svc.Handler, S0109 Script.On.Twice; S0105
as before with on step in its list. Rows in the 14 languages come with the checker's commit.
#Hooks, tasks and states as the checker reads them; is_state; keep/kept
For what hooks, tasks and states do, see Hooks, Tasks and State machines. This part describes exactly how LumaLink reads and checks a head and a body.
#A hook's head
- The row.
Name::functionnames a game function; its row is chosen by, in order: a quoted signature (MR::isNear(const LiveActor *, const Vec3f &, f32)); the number of parameters written; their written types, matched as a call's arguments are. A name no row has is S0047. A count no row of that name takes is S0112. - The parameters take the row's types, as a hook receives them: numbers, values, enums and records by value as
for a call; a pointer to a number, value or enum is
T?, the place it points at (nonefor null);const T &is read, never written; other pointers as views. A parameter written with a type must be that type. selfis the object for a method, a constructor and a destructor; a free or static function has none.- Which hooks:
before,after,wrap,replaceon a function;beforeandafteronly on a constructor, a destructor, or a function the game only tells of (S0113).every override ofonly on a virtual (S0114). A hook in a class only on a member function of the game class it derives from, directly or through a base (S0115). - The result:
-> namenames it for the body;-> Tmust be its type. A function returning nothing has none (S0116). A pointer or reference result is a place and may be written. - Texts. A
const char *parameter istext?, read from the game's bytes at the hook's start; a text written to it reaches the call as its kept copy (abi addition 6), in awrapbeforeproceedand in abeforeon its way out, only when it changed (a script error writes nothing). Aconst char16_t *result takestext/text?: its UTF-16 kept copy, made once per distinct text; a NUL inside is S0918. - A parameter that does not cross may be bound as
_(never read; the kernel passes it through untouched), or the list left out. Bound by a name it is S0060, whose message says to bind it as_.
#A hook's body
skiponly in abeforehook's own body (S0117):skipalone when the function returns nothing (S0118),skip vwith the result's value when it returns one (S0119).resultin anafter, awrapor areplace, in the hook's own body only, never in a closure in it (S0120). In awraporreplace, readingresultbeforeproceedorresult = von some path is S0124.proceedonly in awrap's own body (S0121); at most once on any path, a loop's next round included (S0122).- Every path of a
wraporreplaceof a function with a result gives the result, byproceedorresult = v, at the body's end and at eachreturn(S0123). selfin a constructor'sbefore(the object is not built) or a destructor'safter(it is gone) is S0128.
#stop, go and is_state
stopin a task, a state machine, or a handler that may wait (S0125).go Sin a state machine, for one of its own states;go M.Sin a machine or in a function or hook of the machine's class (S0126 elsewhere).go Sfrom the class is S0130, which lists the class's machines. A state givesenter,updateandexitat most once each (S0129).New:
is_state(S)andis_state(M.S), a standard function,bool: true while the object's machine M is in state S. It is placed and read exactly asgo(S0126, S0127, S0130 name it); its argument is a state's name, never a value (S0131 otherwise). For example:not is_state(OrbKingStates.Dizzy).The rows are by code,
Script.S0109and so on, in the 14 languages.S0109's place is
first, the first handler's file and line (src/main.lum:12), since the two may be in two of the mod's modules:a second "on {what}" in the mod; the first is at {first}.S0110:
wait -N framesorwait -N secondswith a literal N above 0. S0902 (a computed negative wait, at run time) is the run time's. S0107, S0108 and S0111 are the services'.
#keep and kept
keep(value) -> boolinon stop's own body: the value, json data, encoded by the compiler, handed to LumaCore'skeep; true when kept, false when over 1 MiB encoded (lumart also writes that to the mod log). The last call wins.kept<T> -> T?inon start's own body, before anywaiton its path (the kept bytes last untilstartreturns): what the previous load of the mod's code kept this session, decoded as T;nonewhen nothing was kept or the bytes are not a T (a changed struct after a reload), the latter also in the mod log.- Elsewhere S0132 (
Script.Keep.Stop,Script.Kept.Start); T or the value not json data is S0094. - Both are standard names; a mod's own
keeporkepthides them, as for every standard name.
#Codes
S0112 to S0132 as above, with rows and the phrases Script.Result.Before/NotHook, Script.Proceed.NotWrap/
Replace, Script.Self.NotYet/Gone, Script.Keep.Stop, Script.Kept.Start in the 14 languages.
#Services as the checker reads them from their headers
LumaLink reads every service from its header, each the one way below; time is
its first case. What a header does not state yet is a note
S0047 "not known in this game's self-description", never a guess.
#Where a face comes from
use svc.<name>needs a row of the self-description'sservicesand the headerluma_<name>.hof the game's SDK that LumaLink carries for that game version (itsnative/include, embedded when LumaLink is built). A dotted service (system.clipboard) is in its first part's header.- A header out of the one form fails LumaLink's own mirror test when LumaLink is built. A modder never sees that as their error.
#Names
- The table
Luma<Name>Servicegives functions<name>.<member>.baseis not a function, andmodis passed by the compiler. - The prefix is the service's CamelCase name (
LumaSystemClipboardforsystem.clipboard). A struct<Prefix><T>is<name>.<T>. A named enum<Prefix><T>is<name>.<T>, and its cases drop the enum's commonLUMA_..._prefix, each_word in CamelCase:LUMA_TIME_FRAMES->time.Clock.Frames,LUMA_SYSTEM_D3D12->system.Renderer.D3d12. - The event enum
<Prefix>Eventgives events<name>.<kind>, the kind in lower case. - A
#define LUMA_<NAME>_<C>of a whole number is a constant<name>.<C>, upper case as written (time.TIMERS_MOST). The cases of an unnamed enum are constants too.
#Parameters, after mod
| C | LumaScript |
|---|---|
a number, bool |
the same type |
| a named service enum | that enum |
const char *x with no size after it |
text (a NUL inside: abi 6's run-time error) |
const char * or const void * or const uint8_t *, then uint64_t |
one argument: text for char, else bytes; the compiler passes its length |
const <Prefix><T> * |
the struct by value; the compiler sets size and zeroes reserved fields; T? when the comment says `x` (null:, or null: among the parenthesis's other words |
<Prefix><T> by value, LumaColor |
the struct; color (passed as 0xRRGGBBAA) |
X fn, void *user, typedef void (*X)(void *user, args...) in the header |
one fn(args) argument the service calls back: kept until the mod ends, called through the compiler's trampoline (draw.at) |
a handle kind <Prefix><K> (a typedef of LumaHandle) |
<name>.<K> |
a bare LumaHandle |
<name>.Request |
LumaEventFn fn, void *user |
one closure argument |
| a non-const pointer to a number, enum or struct | an out: not an argument, part of the result |
char * or void * or uint8_t *, then uint64_t |
an out buffer: the result is text or bytes |
Any other parameter makes that function not callable from LumaScript (S0060, why ServiceParam). It stays a C function of the header for C mods.
#Results
- Statuses. Each member's comment names every status it returns. The mod's mistakes (ARGUMENT, THREAD,
HANDLE, LIMIT) are reported by the service, and Canceled never reaches running code. Neither is a value a script
sees. The function's answers are its other
LUMA_E_*. - Outs, in order: one is
T, more are a tuple. An out buffer istextorbytes. The compiler asks the whole length first (a null buffer with size 0), then fills. - Without LUMA_PENDING:
- an
int32_tstatus with no answers: the outs, or nothing. A mistake gives zeros or nothing; it was reported. - an
int32_tstatus with answers:T?of the outs (nonefor any answer or mistake), orboolwith no outs (true for LUMA_OK). - an
int64_toruint32_toruint64_tthat is not a status (noLUMA_E_in its comment beyond the mistakes) is the number. - an
int64_tlength with answers (save.get) is folded into its out buffer'sT?.
- an
- With LUMA_PENDING, see Requests and their events.
#Requests and their events
- A request takes
LumaEventFn fn, void *userand gives its handle throughLumaHandle *out. In LumaScript it is called in one of two ways:- with a closure
f(args, fn(e: <name>.<Kind>Event) { }): it returns the handle<name>.<K>?(nonewhen refused), and the closure runs for each of its events, at a frame's start, under the rules in Views. The event record hasstatus(svc.Answer?:nonefor LUMA_OK, else the answer),value(u64, as the event kind's comment says) andflags. - waited, without a closure:
f(args) -> pending<R?>, only for a request whose comment says it closes after its event.Ris the event's value (u64), or the take's result (below). It isnonefor any answer, including refusal.
- with a closure
- Take functions. A member whose comment says
inside the <KIND> event's callis that event's take. It is not callable from a script: the closure's event record has the takentextorbytesasdata, which the compiler takes in the call lumart makes. A waited request'sRis that data. svc.Answeris the enum of the answers the registry defines (Denied,Absent,NotFound,Exists,Io,Timeout,Closed,Memory,Busy,Format,TooLarge,Unreachable,State): everyLUMA_E_*status except the mistakes (ARGUMENT,THREAD,HANDLE,LIMIT) andCANCELLED. It is one language-wide type for every service.- A table's
cancel(LumaHandle)is<name>.cancel(h), returning nothing.
#Handlers and codes
on <name>.<kind>(e) { }is for an event kind that is the table's own mod-wide events: a kind no request names in its comment. For a kind whose events go to the function a request was given, it is S0107{event}'s events go to the function given to {call}; it is not an "on" event.- A member whose comment says it is set by
on <x>(the phraseset by on <x>; time's on_frame and on_step) is not a name of the script. Calling or naming it is S0108{name} is set by "on {what}", not called. - S0111: a literal outside a parameter's range that its comment states as
<a> to <b>(the form<param>: <a> to <b>; time.step's count 1 to 16, time.set_rate's rate 1 to 16000).{name}'s {param} is {found}; it takes {low} to {high}. - A service used without its permission is the validator's L506, said by LumaLink at check time
with the
use's line.
#time read from its header
time.now -> time.Nowandtime.wall -> time.Wall,time.monotonic_ns -> i64,hold,release,set_rate(rate: u32)andstep(count: u32) -> boolwork as thetimeservice describes. For more information, see time.time.timer(clock: time.Clock, after: u64, every: u64, fn(e: time.TimerEvent)) -> time.Timer?: the closure takes the event record, whosevalueis the count. Every request reads the same way, so a script readse.value.time.Clockandtime.Stateare the header's named enumsLumaTimeClockandLumaTimeState, andtime.Timeris its timer handle.
#Codes
S0107, S0108 and S0111 as above, with rows in the 14 languages.
- A handle a call opens at once (no LUMA_PENDING, no closure: content.fx's
startwithLumaContentFxEffect *out) is an out like any other:content.fx.start(...) -> content.fx.Effect. A mistake gives the zero handle; it was reported, and the next call on it is LUMA_E_HANDLE, reported. - A request's event kind is the
a <KIND> event follows(oran) of its comment. The closure isfn(e: <name>.<Kind>Event). A request whose comment names no kind, or a kind its table's event enum lacks, is not callable (S0060, why ServiceParam). A request has no out but its handle. LumaColoriscolor: the compiler packs 0xRRGGBBAA, each channelround(c * 255)of the 0..1 value.- A header with several tables (luma_mods.h: mods, mods.ids, mods.install) names them in its
#define LUMA_<X>_NAME "<a.b>"texts; a face takes none of the names of a dotted service under it. - The shared statuses (registry 4: ARGUMENT for a null or unknown mod, Canceled, THREAD) are not in each member's comment; none is an answer, so no result changes.
#Streams
- A member that takes
LumaEventFn fn, void *userand whose comment has a lineevents: KIND(fields), KIND(fields)is a stream: one handle (or a listener and the sockets it accepts) and many events of several kinds. It may return LUMA_OK with its handle at once (net's udp_open, tcp_listen) or LUMA_PENDING; members without the line use the request form in Requests and their events. - In LumaScript it takes
fn(e: <name>.Event).<name>.Eventis one enum for the service: a case per KIND any of its lines lists, CamelCase (DATAGRAM->Datagram), carrying the listed fields in order, read bymatch. A KIND has the same fields on every line of its service:socket: the event's handle (LumaEvent.handle) as the member's handle kind; ACCEPTED's is the new socket (LumaEvent.valueas a handle), and an accepted socket's own events (DATA, SENT, CLOSED) reach the listener's function with their ownsocket.data:bytes(textwhere the kind's comment says UTF-8 text): the kind's take (take,take_datagram), taken whole by the compiler in the call, elseLumaEvent.data.from: the take's other out (take_datagram'sLumaNetPeer->net.Peer { host: text, port: u16 }).status:svc.Answer?(nonefor LUMA_OK).value:u64.flags:u32.
- The closure runs once per event, at a frame's start, as for a request. The handle the call returns is
<name>.<K>?, as for a request. C mods and the C ABI are unchanged; the line is a comment. - First headers: luma_net.h (both tables, 10 members). The other streams (audio stream_open and tap_open, capture open, input watch_device and open, mods watch_options and watch_mods, a repeating time.timer) take the line next.
#Struct fields, constants and text
- A service struct's pointer field is a value:
const char *istext,const void *(orconst uint8_t *) with auint64_tsize after it isbytes, andconst <Prefix><T> *with auint32_tcount after it is a list of<name>.<T>. The compiler writes the pointer and the count or size for the call; the script never names the count or size field, norsize. A pointer field left out of the literal is null in C; every other field must be written (S0075). A pointer of any other form makes the struct unusable from LumaScript. - The cases of an unnamed
enum { }of a header are constants of the service, upper case as written:LUMA_INPUT_TEXT_NAMEisinput.TEXT_NAME, a whole number. The event enum's cases are events, not constants. - A service enum, a game enum and
svc.Answerare shown in text by the case's name; a constant by its number. text "Key"is the mod's lineKeyin the player's language, the key when the game has none. Made before the game has read its messages (on start), it holds the key and reads as the line when it is used. Read before then, it is its key there, and the mod log says so once. The message tags in a line are bracket words (see Message tags).logtakes anytext: a literal, a string with values placed in it, atext "Key"row, a variable or a result.
use svc.input
use svc.net.internet as internet
fn said(answer: internet.Answer?) -> text {
if let a = answer {
return "failed: {a}"
}
return "ok"
}
on start {
let pad = input.Pad.CoStar
log "pad {pad}, name kind {input.TEXT_NAME}, {said(none)}"
let title = text "Title"
log title
}The game's log gets pad CoStar, name kind 2, ok, then Title: the row is read in on start, before the game's
messages exist, so it is its key, and the mod log says so. Kept in a variable and logged in on stage, it is the
mod's line. For each rule with its own example, see Text and service values.