EVT script API: callable C functions reference

The EVT script API is the collection of C functions that scripts invoke using the Call instruction. These functions bridge the high-level scripting layer and the game engine, handling everything from rotating a map model to playing an audio cue. Every callable exposes a standardized signature, reads its arguments from the script’s read pointer, and signals completion through an ApiStatus return value.

The API_CALLABLE signature

The API_CALLABLE macro (defined in include/macros.h) expands to the full C function declaration:

#define API_CALLABLE(name) ApiStatus name(Evt* script, bool isInitialCall)

So a callable named TranslateModel is declared as:

ApiStatus TranslateModel(Evt* script, bool isInitialCall);

Inside the function body, arguments passed from the script are read sequentially from script->ptrReadPos:

API_CALLABLE(TranslateModel) {
    Bytecode* args = script->ptrReadPos;
    s32 modelIndex = evt_get_variable(script, *args++);
    f32 x = evt_get_float_variable(script, *args++);
    f32 y = evt_get_float_variable(script, *args++);
    f32 z = evt_get_float_variable(script, *args++);
    // ... apply transform ...
    return ApiStatus_DONE2;
}

isInitialCall is true on the first invocation. If the function returns ApiStatus_BLOCK, the VM calls it again next frame with isInitialCall set to false. Use this pattern to implement multi-frame blocking operations:

API_CALLABLE(WaitForSomething) {
    if (isInitialCall) {
        // one-time setup
        script->functionTemp[0] = start_async_operation();
    }
    if (operation_done(script->functionTemp[0])) {
        return ApiStatus_DONE2;
    }
    return ApiStatus_BLOCK; // resume next frame
}

Invoking callables from scripts

Use the Call macro to invoke any API_CALLABLE function. Arguments follow the function pointer:

Call(TranslateModel, MODEL_gate, Float(0.0), Float(5.0), Float(0.0))
Call(SetNpcPos, NPC_Goomba, 100, 0, 200)
Call(DisablePlayerInput, true)

The @evtapi Doxygen tag marks declarations in the source as callable from EVT scripts. You will find it on every function listed below.

Map and model functions

Declared in include/script_api/common.h under the Map group.

Function	Description
`TranslateModel`	Applies a translation to a model’s user transform matrix.
`RotateModel`	Applies a rotation to a model’s user transform matrix.
`ScaleModel`	Applies a scale to a model’s user transform matrix.
`GetModelIndex`	Returns the list index of a model from its tree index.
`InvalidateModelTransform`	Marks a model’s transform as dirty.
`CloneModel`	Creates a clone of an existing model.
`GetModelCenter`	Retrieves the center position of a model.
`EnableModel`	Shows or hides a model.
`SetGroupVisibility`	Shows or hides all models in a transform group.
`EnableGroup`	Enables or disables a model group.
`MakeTransformGroup`	Creates a new transform group.
`TranslateGroup`	Translates all models in a transform group.
`RotateGroup`	Rotates all models in a transform group.
`ScaleGroup`	Scales all models in a transform group.
`SetTexPanner`	Assigns a texture panner to a model.
`EnableTexPanning`	Enables or disables texture panning on a model.
`SetTexPanOffset`	Sets the texture pan offset directly.
`SetCustomGfx`	Assigns custom GFX to a model.
`SetModelCustomGfx`	Assigns custom GFX builders to a specific model.
`SetModelTexVariant`	Changes a model’s texture variant.
`SetModelFlags`	Sets bitfield flags on a model.
`ModifyColliderFlags`	Sets or clears flags on a collision object.
`GetColliderCenter`	Retrieves the center point of a collider.
`ParentColliderToModel`	Parents a collider’s transform to a model.
`UpdateColliderTransform`	Forces a collider to update from its parent model.
`SetZoneEnabled`	Enables or disables a zone.
`GotoMap`	Initiates a map transition to the named map at the given entry.
`GotoMapByID`	Initiates a map transition by map ID.
`GetEntryID`	Retrieves the entry ID used when the current map was loaded.
`GetMapID`	Retrieves the current map’s ID.
`GetLoadType`	Returns how the map was loaded (e.g. `LOAD_FROM_FILE_SELECT`).
`SetRenderMode`	Sets the render mode for a model.
`PlaySoundAtModel`	Plays a sound effect positioned at a model.
`PlaySoundAtCollider`	Plays a sound effect positioned at a collider.
`MakeLocalVertexCopy`	Creates a local vertex copy of a model for vertex animation.
`ResetFromLava`	Resets the player to the last safe position after touching lava.

Animated model functions

Function	Description
`InitAnimatedModels`	Initializes the animated model system.
`LoadAnimatedModel`	Loads an animated model.
`LoadAnimatedMesh`	Loads an animated mesh.
`PlayModelAnimation`	Starts an animation on a loaded model.
`PlayModelAnimationStartingFrom`	Starts an animation from a given frame.
`ChangeModelAnimation`	Transitions to a different animation.
`SetAnimatedModelRootPosition`	Sets the root position of an animated model.
`GetAnimatedModelRootPosition`	Reads the root position.
`SetAnimatedModelRootRotation`	Sets the root rotation.
`SetAnimatedModelRootScale`	Sets the root scale.
`SetAnimatedModelRenderMode`	Sets the render mode.
`DeleteAnimatedModel`	Removes an animated model.
`GetAnimatedNodePosition`	Gets the world position of a named node.
`GetAnimatedNodeRotation`	Gets the rotation of a named node.

Camera functions

Declared in include/script_api/common.h under the Camera group.

Function	Description
`SetCamEnabled`	Enables or disables a camera.
`SetCamPerspective`	Sets FOV, near/far clip, and update mode.
`SetCamBGColor`	Sets the background clear color.
`SetCamLeadPlayer`	Enables or disables the camera leading ahead of the player.
`SetCamLeadScale`	Sets how far ahead the camera leads.
`SetCamTarget`	Points the camera at a target position.
`SetCamLookTarget`	Sets the camera look-at target.
`InterpCamTargetPos`	Smoothly interpolates the camera to a new target.
`ShakeCam`	Applies a screen shake effect.
`PanToTarget`	Pans the camera to focus on a target.
`UseSettingsFrom`	Copies camera settings from a zone.
`LoadSettings`	Applies a full set of camera parameters.
`SetCamSpeed`	Sets the camera tracking speed.
`GetCamPosition`	Reads the current camera position.
`WaitForCam`	Blocks until the camera finishes interpolating.
`ResetCam`	Resets the camera to default parameters.
`AdjustCam`	Adjusts camera parameters incrementally.
`GrabCamera`	Locks the camera to a fixed position.
`SetCamViewport`	Sets the rendering viewport for a camera.

NPC functions

Declared in include/script_api/common.h under the NPC group.

Function	Description
`CreateNpc`	Creates an NPC instance.
`DeleteNpc`	Removes an NPC.
`SetNpcPos`	Teleports an NPC to a world position.
`GetNpcPos`	Reads an NPC’s current world position.
`SetNpcRotation`	Sets NPC rotation angles.
`SetNpcScale`	Sets NPC scale.
`SetNpcSpeed`	Sets the NPC’s movement speed.
`SetNpcAnimation`	Changes the NPC’s current animation.
`GetNpcAnimation`	Reads the NPC’s current animation ID.
`NpcMoveTo`	Commands an NPC to walk to a position.
`NpcJump0` / `NpcJump1`	Makes an NPC jump.
`NpcFlyTo`	Makes an NPC fly to a position.
`SetNpcYaw`	Sets the NPC’s facing direction.
`GetNpcYaw`	Reads the NPC’s facing direction.
`NpcFacePlayer`	Turns the NPC to face the player.
`NpcFaceNpc`	Turns the NPC to face another NPC.
`SetNpcFlagBits`	Sets or clears flags on an NPC.
`SetNpcCollisionSize`	Overrides the NPC’s collision dimensions.
`EnableNpcShadow`	Shows or hides the NPC’s shadow.
`DisablePartnerAI`	Suspends the partner’s AI.
`EnablePartnerAI`	Resumes the partner’s AI.
`GetPartnerPos`	Reads the partner’s current world position.
`PlaySoundAtNpc`	Plays a sound positioned at an NPC.

Encounter and AI functions

Function	Description
`MakeNpcs`	Instantiates all NPCs from an NPC table.
`RemoveNpc`	Removes an NPC from the map.
`StartBattle`	Initiates a battle encounter.
`StartBattleWith`	Initiates a battle with a specific formation.
`StartBossBattle`	Initiates a boss battle.
`GetBattleOutcome`	Returns the result of the most recent battle.
`DoNpcDefeat`	Runs the defeat sequence for an NPC encounter.
`SetBattleMusic`	Sets the music for an upcoming battle.
`BindNpcAI`	Binds an AI script to an NPC.
`BindNpcIdle`	Binds an idle script to an NPC.
`BindNpcInteract`	Binds an interaction script to an NPC.
`BindNpcHit`	Binds a hit-reaction script.
`BindNpcDefeat`	Binds a defeat script.
`SetNpcVar` / `GetNpcVar`	Sets or reads NPC-local state variables.
`ClearDefeatedEnemies`	Clears the defeated-enemy flag table.

Player functions

Declared in include/script_api/common.h under the Player group.

Function	Description
`SetPlayerPos`	Teleports the player to a world position.
`GetPlayerPos`	Reads the player’s world position.
`DisablePlayerInput`	Blocks all player and partner input.
`DisablePlayerPhysics`	Disables player collision physics.
`SetPlayerSpeed`	Sets the player’s movement speed.
`SetPlayerAnimation`	Changes the player’s current animation.
`SetPlayerActionState`	Forces the player into an action state.
`GetPlayerActionState`	Reads the player’s current action state.
`PlayerMoveTo`	Commands the player to walk to a position.
`PlayerJump` / `PlayerJump1` / `PlayerJump2`	Makes the player jump.
`InterpPlayerYaw`	Smoothly rotates the player to face a direction.
`FacePlayerTowardPoint`	Instantly faces the player toward a world point.
`HidePlayerShadow`	Shows or hides the player’s shadow.
`SetPlayerCollisionSize`	Overrides the player’s collision dimensions.
`EnablePartner` / `DisablePartner`	Enables or disables a partner in the party.
`FullyRestoreHPandFP`	Restores the player to full HP and FP.
`UseExitHeading` / `UseEntryHeading`	Sets the player’s walk direction for map transitions.
`WaitForPlayerMoveToComplete`	Blocks until a `PlayerMoveTo` finishes.
`WaitForPlayerInputEnabled`	Blocks until player input is re-enabled.
`PlaySoundAtPlayer`	Plays a sound positioned at the player.

Message and dialogue functions

Declared under the Message group.

Function	Description
`SpeakToPlayer`	Displays a dialogue bubble from an NPC directed at the player.
`SpeakToNpc`	Displays a dialogue bubble between two NPCs.
`EndSpeech`	Closes the current dialogue bubble.
`ContinueSpeech`	Continues dialogue from the same speaker.
`ShowMessageAtScreenPos`	Shows a message box at a screen-space position.
`ShowMessageAtWorldPos`	Shows a message box anchored to a world position.
`CloseMessage`	Closes the active message box.
`ShowChoice`	Displays a choice prompt and blocks for selection.
`CloseChoice`	Dismisses a choice prompt.
`SetMessageText`	Sets the text string used in the next message.
`SetMessageValue`	Sets a numeric value displayed inside a message.
`SetMessageImages`	Sets images embedded in a message box.

Audio functions

Declared under the Audio group.

Function	Description
`SetMusic`	Starts a song on a music player with a given volume.
`FadeInMusic`	Fades in the current song.
`FadeOutMusic`	Fades out the current song.
`PushSong` / `PopSong`	Saves and restores the current song on a stack.
`PushBattleSong` / `PopBattleSong`	Saves and restores the battle song.
`SetBattleSong`	Sets the track used for battle music.
`SetTrackVolumes`	Sets per-track volume levels.
`PlaySound`	Plays a one-shot sound effect.
`PlaySoundWithVolume`	Plays a sound at a specific volume.
`PlaySoundAt`	Plays a sound at a world position.
`StopSound`	Stops a currently playing sound.
`PlayAmbientSounds`	Starts ambient audio loops for the current area.
`ClearAmbientSounds`	Stops ambient audio.
`RegisterMusicEvents`	Registers music event callbacks.
`PollMusicEvents`	Polls active music events.

Item functions

Declared under the Item group.

Function	Description
`AddItem`	Adds an item to the player’s inventory.
`AddKeyItem`	Adds a key item to the player’s inventory.
`RemoveItem`	Removes an item by ID.
`RemoveItemAt`	Removes an item at a specific inventory slot.
`RemoveKeyItemAt`	Removes a key item at a specific slot.
`FindItem`	Searches the inventory for an item by ID.
`FindKeyItem`	Searches for a key item.
`HasKeyItem`	Returns true if the player holds a given key item.
`ShowKeyChoicePopup`	Shows a popup prompting the player to choose a key item.
`ShowConsumableChoicePopup`	Shows a popup for consumable items.
`CloseChoicePopup`	Dismisses an item choice popup.

Math and utility functions

Declared under the Math group.

Function	Description
`MakeLerp`	Initializes a linear interpolation from a start value to an end value over a number of frames, with an easing mode.
`UpdateLerp`	Advances the lerp by one frame; stores the current value in `LVar0` and a completion flag in `LVar1`.
`RandInt`	Generates a random integer in a given range.
`GetDist2D`	Computes the 2D distance between two points.
`AddVectorPolar`	Adds a vector defined by angle and length to a position.
`GetAngleBetweenNPCs`	Computes the angle from one NPC to another.
`GetAngleToPlayer`	Computes the angle from a world point to the player.
`IsPlayerWithin`	Tests whether the player is within a given radius.
`AwaitPlayerApproach`	Blocks until the player is within a radius.
`AwaitPlayerLeave`	Blocks until the player is outside a radius.
`LoadPath`	Loads a world-space path for path-following movement.
`GetNextPathPos`	Advances along a loaded path and returns the next position.
`SetTimeFreezeMode`	Freezes or unfreezes game time.
`ClampAngleInt` / `ClampAngleFloat`	Clamps an angle to the range [0, 360).

Effects and FX

The convenience macro PlayEffect(effect, ...) (declared in include/script_api/macros.h) expands to Call(PlayEffect_impl, ...) and accepts 1–14 arguments. Pass the effect ID as the first argument and an optional subtype and positional parameters depending on the effect.

Battle-specific API

include/script_api/battle.h declares additional callables available only during battles. These include camera presets (UseBattleCamPreset, SetBattleCamTarget, MoveBattleCamOver), actor movement (SetActorPos, SetGoalPos, SetGoalToTarget), animation (SetAnimation, GetAnimation), damage application (ItemDamageEnemy, ItemCheckHit), status effects, and actor speech (ActorSpeak, EndActorSpeech).

Map-specific API

include/script_api/map.h declares callables available only in world maps. These include MakeNpcs (instantiate NPCs from a table), MakeShop, MakeShopOwner, CreatePushBlockGrid, and trigger-bound common scripts such as EnterWalk, ExitWalk, EnterSingleDoor, ExitDoubleDoor, and others declared as extern EvtScript.

Functions whose names begin with func_ (e.g. func_802CF54C) are not yet reverse-engineered. Their behavior is unknown; do not rely on them in new scripts.

Get Started

Contributing

EVT Scripting

Game Systems

Data Reference

EVT script API: callable C functions reference

The API_CALLABLE signature

Invoking callables from scripts

Map and model functions

Animated model functions

Camera functions

NPC functions

Encounter and AI functions

Player functions

Message and dialogue functions

Audio functions

Item functions

Math and utility functions

Effects and FX

Battle-specific API

Map-specific API

Build docs developers (and LLMs) love

Get Started

Contributing

EVT Scripting

Game Systems

Data Reference

Documentation Index

​The API_CALLABLE signature

​Invoking callables from scripts

​Map and model functions

​Animated model functions

​Camera functions

​NPC functions

​Encounter and AI functions

​Player functions

​Message and dialogue functions

​Audio functions

​Item functions

​Math and utility functions

​Effects and FX

​Battle-specific API

​Map-specific API

Build docs developers (and LLMs) love

The API_CALLABLE signature

Invoking callables from scripts

Map and model functions

Animated model functions

Camera functions

NPC functions

Encounter and AI functions

Player functions

Message and dialogue functions

Audio functions

Item functions

Math and utility functions

Effects and FX

Battle-specific API

Map-specific API