EVT_FIXED_TO_FLOAT
#define EVT_FIXED_TO_FLOAT(x) source
Progammatically converts Float --> f32
FLOAT_TO_FIXED
#define FLOAT_TO_FIXED(x) source
Progammatically converts f32 --> Float
Ref
LocalVar
#define LocalVar(INDEX) source
Local Word. A variable local to the current thread. LWs are copied to any threads created by this one (Exec, ExecWait, Thread, ChildThread). Additionally, ExecWait copies LWs back from the spawned thread when it completes.
Range: 0 <= v < 0x10
MapVar
#define MapVar(INDEX) source
Global Word. A variable global to all threads. Cleared upon entering a new map.
Range: 0 <= v < 0x10
LocalFlag
#define LocalFlag(INDEX) source
Local Flag. A boolean variable local to the current thread. LFs are copied to any threads created by this one (Exec, ExecWait, Thread, ChildThread). Additionally, ExecWait copies LFs back from the spawned thread when it completes.
Range: 0 <= v < 0x60
MapFlag
#define MapFlag(INDEX) source
Global Flag. A boolean variable global to all threads. Cleared upon entering a new map.
Range: 0 <= v < 0x60
AreaFlag
#define AreaFlag(INDEX) source
Local Save World Flag. A boolean variable local to the current world area, saved in the savefile. Cleared upon entering a new world area.
Used to track whether items that respawn, such as coins, Goomnuts, or Koopa Leaves, have been collected.
Range: 0 <= v < 0x100
GameFlag
#define GameFlag(INDEX) source
Global Save World Flag. A boolean variable saved in the savefile.
Used to track whether badges, items, etc. have been collected or whether NPCs have been interacted with.
Range: 0 <= v < 0x800
AreaByte
#define AreaByte(INDEX) source
Local Saved Byte. A variable local to the current world area, saved in the savefile. Cleared upon a new world area.
Rarely used. Most common use is for NPCs with dialogue that changes depending on the number of times you have interacted with them in their 'recent memory' (i.e. until you leave the area).
Range: 0 <= v < 0x10
GameByte
#define GameByte(INDEX) source
Global Saved Byte. A variable saved in the save file.
Used for almost all savefile state.
ArrayVar
#define ArrayVar(INDEX) source
User Word. A variable stored within the current thread's array. You can load an array with UseArray or temporarily allocate one with MallocArray, then get/set values with the ArrayVar(index) macro.
Range: 0 <= v
ArrayFlag
#define ArrayFlag(INDEX) source
User Flag. A boolean variable stored within the current thread's flag array. The flag array is distinct from the word array (unlike UseBuf and UseFBuf).
Range: 0 <= v
EVT_ENTITY_ID_BIT
#define EVT_ENTITY_ID_BIT source
An entity index. Entities are assigned indices in the order they are created with Call(MakeEntity, ...). Supported in BindTrigger and BindPadlock only.
End
#define End source
Signals the end of EVT script data. A script missing this will likely crash on load.
Return
#define Return source
Kills the current EVT thread. A script missing a return will live - but do nothing - forever, or until something else kills it (e.g. leaving the map).
Jump
#define Jump(EVT_SOURCE) source
Jumps to a given instruction pointer and begins execution from there. You can jump to a different EVT source and labels etc. will be loaded as expected. The timescale for the current thread is also reset to the global default.
Label
#define Label(LABEL_ID) source
Marks this point in the script as a Goto target.
Range: 0 <= LABEL_ID <= 0x16
Goto
Loop
#define Loop(TIMES) source
Marks the beginning of a loop.
Loop(TIMES) ... EndLoop
The variable or value given in TIMES is decremented upon each loop iteration. After the "1" iteration completes, the loop exits. Use Loop(0) for an infinite loop; make sure it breaks or blocks to avoid a freeze.
Up to 8 loops may be nested within a single script.
EndLoop
BreakLoop
Wait
WaitSecs
IfEq
#define IfEq(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR == RVAR.
IfEq(LVAR, RVAR) ... Else ... EndIf
The Else block is optional.
IfNe
#define IfNe(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR != RVAR.
IfLt
#define IfLt(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR < RVAR.
IfGt
#define IfGt(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR <= RVAR.
IfLe
#define IfLe(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR > RVAR.
IfGe
#define IfGe(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if LVAR >= RVAR.
IfFlag
#define IfFlag(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if the RVAR flag is set on LVAR, i.e. (LVAR & RVAR) != 1.
IfNotFlag
#define IfNotFlag(LVAR, RVAR) source
Marks the beginning of an if statement that only executes if the RVAR flag is unset on LVAR, i.e. (LVAR & RVAR) == 0.
Else
EndIf
Switch
#define Switch(LVAR) source
Marks the start of a switch statement.
Switch(LVAR) CaseEq(RVAR) ... EndSwitch
Unlike C, EVT switch statements do not have fallthrough by default. If you want to opt-in to fallthrough, use CaseOrEq.
Up to 8 switch statements may be nested within a single script.
SwitchConst
#define SwitchConst(LCONST) source
Marks the start of a switch statement where the given value is treated as-is instead of using evt_get_variable. That is, SwitchConst(LocalVar(0)) will switch over the value 0xFE363C80 instead of the value contained within LocalVar(0).
CaseEq
#define CaseEq(RVAR) source
Marks the start of a switch case that executes only if LVAR == RVAR. It also marks the end of any previous case.
CaseNe
#define CaseNe(RVAR) source
Marks the start of a switch case that executes only if LVAR != RVAR. It also marks the end of any previous case.
CaseLt
#define CaseLt(RVAR) source
Marks the start of a switch case that executes only if LVAR < RVAR. It also marks the end of any previous case.
CaseGt
#define CaseGt(RVAR) source
Marks the start of a switch case that executes only if LVAR <= RVAR. It also marks the end of any previous case.
CaseLe
#define CaseLe(RVAR) source
Marks the start of a switch case that executes only if LVAR > RVAR. It also marks the end of any previous case.
CaseGe
#define CaseGe(RVAR) source
Marks the start of a switch case that executes only if LVAR >= RVAR. It also marks the end of any previous case.
CaseDefault
#define CaseDefault source
Marks the start of a switch case that executes unconditionally. It also marks the end of any previous case.
CaseOrEq
#define CaseOrEq(RVAR) source
Marks the start of a switch case that executes only if LVAR == RVAR. It also marks the end of any previous case. Unlike CaseEq, CaseOrEq will fallthrough to the next case until EndCaseGroup is reached.
CaseAndEq
#define CaseAndEq(RVAR) source
Marks the start of a switch case that executes only if LVAR == RVAR. It also marks the end of any previous case. Similar to CaseOrEq, CaseAndEq has fallthrough. However, if LVAR != RVAR, fallthrough does not apply.
CaseFlag
#define CaseFlag(RVAR) source
Marks the start of a switch case that executes only if the RVAR flag is set on LVAR, i.e. (LVAR & RVAR) != 1. It also marks the end of any previous case.
EndCaseGroup
#define EndCaseGroup source
Marks the end of a switch case group (CaseOrEq and/or CaseAndEq), stopping fallthrough.
CaseRange
#define CaseRange(MIN, MAX) source
Marks the start of a switch case that executes only if MIN <= LVAR <= MAX (inclusive). It also marks the end of any previous case.
BreakSwitch
#define BreakSwitch source
Marks the end of a switch case
EndSwitch
Set
SetConst
#define SetConst(VAR, CONST) source
Sets the given variable to a given value, skipping the evt_get_variable call. That is, SetConst(LocalVar(0), LocalVar(1)) will set LocalVar(0) to 0xFE363C81 instead of copying the value of LocalVar(1) into LocalVar(0).
SetF
#define SetF(VAR, FLOAT_VALUE) source
Sets the given variable to a given value, but supports Floats.
UseBuf
BufRead1
#define BufRead1(VAR) source
Consumes the next s32 from the buffer and stores it in the given variable.
BufRead2
#define BufRead2(VAR1, VAR2) source
Consumes the next two s32s from the buffer and stores them in the given variables.
BufRead3
#define BufRead3(VAR1, VAR2, VAR3) source
Consumes the next three s32s from the buffer and stores them in the given variables.
BufRead4
#define BufRead4(VAR1, VAR2, VAR3, VAR4) source
Consumes the next four s32s from the buffer and stores them in the given variables.
BufPeek
#define BufPeek(OFFSET, VAR) source
Gets the s32 at the given offset of the buffer and stores it in the given variable, without consuming it.
UseFBuf
#define UseFBuf(FLOAT_PTR) source
Identical to UseBuf. Beware that the int buffer and the float buffer are not distinct.
FBufRead1
#define FBufRead1(VAR) source
Consumes the next f32 from the buffer and stores it in the given variable.
FBufRead2
#define FBufRead2(VAR1, VAR2) source
Consumes the next two f32s from the buffer and stores them in the given variables.
FBufRead3
#define FBufRead3(VAR1, VAR2, VAR3) source
Consumes the next three f32s from the buffer and stores them in the given variables.
FBufRead4
#define FBufRead4(VAR1, VAR2, VAR3, VAR4) source
Consumes the next four f32s from the buffer and stores them in the given variables.
FBufPeek
#define FBufPeek(OFFSET, VAR) source
Gets the f32 at the given offset of the buffer and stores it in the given variable, without consuming it.
UseArray
#define UseArray(INT_PTR) source
Loads an s32 array pointer into the current thread for use with ArrayVar(INDEX).
UseFlagArray
#define UseFlagArray(PACKED_FLAGS_PTR) source
Loads an s32 array pointer into the current thread for use with UF(INDEX). Flags are stored in a 'packed' structure where indices refer to bits.
MallocArray
#define MallocArray(SIZE, OUT_PTR_VAR) source
Allocates a new array of the given size for use with ArrayVar(INDEX). EVT scripts do not have to worry about freeing this array.
BitwiseAnd
#define BitwiseAnd(VAR, VALUE) source
VAR &= VALUE
BitwiseAndConst
#define BitwiseAndConst(VAR, CONST) source
VAR &= CONST, but CONST is treated as-is rather than dereferenced with evt_get_variable.
BitwiseOr
BitwiseOrConst
#define BitwiseOrConst(VAR, CONST) source
VAR |= CONST, but CONST is treated as-is rather than dereferenced with evt_get_variable.
Exec
#define Exec(EVT_SOURCE) source
Launches a new thread. The following values are copied from the current thread to the new thread:
- LFs
- LWs
- Array pointer
- Flag array pointer
- Priority
- Group
ExecGetTID
#define ExecGetTID(EVT_SOURCE, OUTVAR) source
Identical to Exec, but the newly-launched thread ID is stored in OUTVAR. The other thread may be interacted with using KillThread, SuspendThread, ResumeThread, and IsThreadRunning.
ExecWait
#define ExecWait(EVT_SOURCE) source
Launches a new child thread. Blocks for at least one frame unless the child thread is made to have a higher priority than the parent.
The following values are inherited and then copied back to the parent thread upon completion:
- LFs
- LWs
- Array pointer
- Flag array pointer
- Priority
- Group
Child threads are killed, suspended, and resumed as their parents are, for example, a different thread using KillThread to kill a parent thread would also kill its child thread(s) launched by this command.
BindTrigger
#define BindTrigger( EVT_SOURCE, TRIGGER, COLLIDER_ID, UNK_A3, TRIGGER_PTR_OUTVAR ) source
Sets up a script to launch when a particular event is triggered.
Valid triggers:
- TRIGGER_WALL_PUSH
- TRIGGER_FLOOR_TOUCH
- TRIGGER_WALL_PRESS_A (displays "!" icon above player)
- TRIGGER_FLOOR_JUMP
- TRIGGER_WALL_TOUCH
- TRIGGER_FLOOR_PRESS_A
- TRIGGER_WALL_HAMMER
- TRIGGER_GAME_FLAG_SET (TODO: rename)
- TRIGGER_AREA_FLAG_SET (TODO: rename)
- TRIGGER_CEILING_TOUCH
- TRIGGER_FLOOR_ABOVE
- TRIGGER_POINT_BOMB (takes Vec3f* instead of collider ID)
For the COLLIDER_ID param, the following values are accepted:
- Collider ID
- Entity ID (use EVT_ENTITY_INDEX)
- Pointer to a Vec3f (for TRIGGER_POINT_BOMB only)
Only one thread will run for a trigger at once.
BindPadlock
#define BindPadlock( EVT_SOURCE, TRIGGER, COLLIDER_ID, ITEM_LIST, UNK_A3, TRIGGER_PTR_OUTVAR ) source
Similar to BindTrigger, but also takes arguments for the item list to show.
Unbind
KillThread
#define KillThread(TID) source
Kills a thread by its thread ID.
SetPriority
#define SetPriority(PRIORITY) source
Sets the current thread's priority. Higher-priority threads execute before lower-priority threads on each frame.
SetTimescale
#define SetTimescale(TIMESCALE) source
Sets the current thread's timescale. This is a multiplier applied to Wait and Wait_SECONDS.
SetGroup
#define SetGroup(GROUP) source
Sets the current thread's group. Group value meanings are currently not known.
SuspendGroup
#define SuspendGroup(GROUP) source
Suspends all threads in a group.
ResumeGroup
#define ResumeGroup(GROUP) source
Resumes all threads in a group.
SuspendOthers
#define SuspendOthers(GROUP) source
Suspends all threads in a group, except the current thread.
ResumeOthers
#define ResumeOthers(GROUP) source
Resumes all threads in a group, except the current thread.
SuspendThread
#define SuspendThread(TID) source
Suspends all threads in a group, except the current thread.
ResumeThread
#define ResumeThread(TID) source
Resumes a thread by its thread ID.
IsThreadRunning
#define IsThreadRunning(TID, OUTVAR) source
Sets OUTVAR to true/false depending on whether a thread with the given ID exists (i.e. has not been killed).
Thread
#define Thread source
Marks the start of a thread block. Commands between this and a matching EndThread will be executed on their own, new thread instead of on the current thread.
EndThread
ChildThread
#define ChildThread source
Marks the start of a child thread block. Commands between this and a matching EndChildThread will be executed as a new child thread instead of on the current thread.
Child threads are killed if the parent thread dies, so the following script does NOT set the player's position:
ChildThread Wait_SECONDS(1) // child thread will be killed whilst waiting Call(SetPlayerPos, NPC_DISPOSE_LOCATION) // will not be executed EndChildThread Return // parent thread dies
EndChildThread
#define EndChildThread source
Marks the end of a child thread block.
Call
#define Call(FUNC, ARGS...) source
Calls a given C EVT API function with any number of arguments.
An API function has the following signature:
ApiStatus ApiFunction(Evt* script, s32 isInitialCall);
This function could then be called with the following command:
Call(ApiFunction)
The given arguments can be accessed from the API function using thread->ptrReadPos.
EVT_DEBUG_LOG
#define EVT_DEBUG_LOG(STRING) source
Does nothing in release version
DebugPrintVar
#define DebugPrintVar(VAR) source
Prints variable name and value
BreakPoint
#define BreakPoint(TEXT) source
Halt execution after this command
EVT_SETUP_CAMERA_DEFAULT
#define EVT_SETUP_CAMERA_DEFAULT(r, g, b) source
Enable camera using standard parameters for clip distances and FOV @param r background red color @param g background green color @param b background blue color
EVT_SETUP_CAMERA_NO_LEAD
#define EVT_SETUP_CAMERA_NO_LEAD(r, g, b) source
Enable camera using standard parameters for clip distances and FOV with LeadPlayer disabled @param r background red color @param g background green color @param b background blue color
EVT_SETUP_CAMERA_MIM
#define EVT_SETUP_CAMERA_MIM() source
Enable camera for AREA_MIM using a closer far clip distance and appropriate background color