Scripting Cheat Sheet

A simple list of commands to make common cutscene actions, intended for those with little programming experience. Mostly example snippets that can be copied and pasted or simple instructions. For programmers, in-depth documentation of the base engine can be found on Github.

For those that want to learn Lua and better understand the way it all works, it is recommended to start with a Tutorial.

How do I…

Make the text pause in the middle of a dialogue?

Edit the string to include the pause tag. Ex.

Ready,[pause=30] set,[pause=0] GO!

A pause of 60 will pause text for 60 frames (one second) before it continues. A pause of 0 will pause text and prompt the player to press Confirm before it continues.

Color text differently?

Edit the string to include the color tag. Ex.

Welcome to [color=#FFC663]Treasure Town[color]!

The tag accepts colors in hex. Don’t forget to close the tag! Additionally, you can access colored names for Pokemon, item, move, zone, etc. using GetColoredName(), GetIconName(), or GetDisplayName()

local item = RogueEssence.Dungeon.InvItem(1)
UI:WaitShowDialogue(item:GetDisplayName())

Other Tags?

Text Guide

Ask the player a question?

Yes/No:

UI:ChoiceMenuYesNo(STRINGS:Format(MapStrings['String_001']), false)
UI:WaitForChoice()
ch = UI:ChoiceResult()
if ch then
    UI:WaitShowDialogue(STRINGS:Format(MapStrings['String_002']))
else
    UI:WaitShowDialogue(STRINGS:Format(MapStrings['String_003']))
end

Custom:

choices = {STRINGS:Format(MapStrings['Strings_001']),
    STRINGS:Format(MapStrings['Strings_002']),
    STRINGS:Format(MapStrings['Strings_003'])}

UI:BeginChoiceMenu(STRINGS:Format(MapStrings['Strings_004']), choices, 1, 3)
UI:WaitForChoice()
result = UI:ChoiceResult()
if result == 1 then
    UI:WaitShowDialogue(STRINGS:Format(MapStrings['Strings_004']))
elseif result == 2 then
    UI:WaitShowDialogue(STRINGS:Format(MapStrings['Strings_005']))
else
    UI:WaitShowDialogue(STRINGS:Format(MapStrings['Strings_006']))
end

Change a character’s portrait emotion for speaking?

UI:SetSpeakerEmotion("Happy")

The list of possible portrait emotions can be found in Base/GFXParams.xml. Look inside the Emotions tag.

Make a character do a sprite emote?

GROUND:CharSetEmote(player, 8, 1)

Argument 2 is the index of the emote, found by editing emotes. Argument 3 is the number of repetitions to animate the emote with.

Make a character turn? Walk somewhere?

GROUND:EntTurn(player, Direction.UpLeft)
GROUND:CharAnimateTurn(player, Direction.DownRight, 4, true)
GROUND:MoveInDirection(player, Direction.Down, 24, false, 2)
GROUND:MoveInDirection(player, Direction.DownLeft, 24, false, 2)
GROUND:MoveInDirection(player, Direction.Left, 24, false, 2)

Make a character move with custom animation?

GROUND:AnimateInDirection(player, "Hurt", Direction.Right, Direction.Left, 24, 3, 2)

This will make a character appear to be dragged leftward while facing right in a Hurt animation. The “3” signifies how long each frame of animation should take in 1/60ths of a second. The “2” signifies the speed of movement. 2 is normal walking speed.

Make two or more characters move at once?

You can achieve this by calling BranchCoroutine and giving it a function that does the secondary actions:

local coro1 = TASK:BranchCoroutine(function() test_grounds.Walk_Sequence(partner1) end)
local coro2 = TASK:BranchCoroutine(function() test_grounds.Walk_Sequence(partner2) end)
GROUND:MoveInDirection(player, Direction.Up, 72, false, 2)
GROUND:CharAnimateTurn(player, Direction.DownLeft, 4)
 
TASK:JoinCoroutines({coro1,coro2})

You would then define the function elsewhere:

function test_grounds.Walk_Sequence(character)
  GROUND:MoveInDirection(character, Direction.Up, 72, false, 2)
  GROUND:CharAnimateTurn(character, Direction.DownRight, 4)
end

Make a character perform an animation?

GROUND:CharSetAnim(chara, "Attack", false) --animates once
GROUND:CharSetAnim(chara, "Idle", true) --animation loops forever
GROUND:CharEndAnim(chara) --stops a looping animation
GROUND:CharWaitAnim(chara, "Attack") --animates and waits until done

The list of possible animations can be found in Content/GFXParams.xml. Look inside the Actions tag.

This will play an animation that stops at the frame where the attack comes out. Useful for bosses making their attack pose before a fight whoosh.

Make a sound? A Fanfare? Change the BGM?

SOUND:PlaySE("Battle/DUN_Explosion")
SOUND:PlayBattleSE("DUN_Explosion")
SOUND:LoopSE("Battle/EVT_Applause")
SOUND:LoopBattleSE("EVT_Applause")
SOUND:StopSE("Battle/EVT_Applause")
SOUND:StopBattleSE("EVT_Applause")
SOUND:PlayFanfare("Fanfare/Treasure")
SOUND:PlayBGM(“Title.ogg”, true)

The list of possible sounds can be found in Content/Sound. The list of music can be found in Content/Music. Music must use LOOPSTART/LOOPLENGTH tags to loop properly.

Make a looping sound?

SOUND:LoopSE("Battle/EVT_Applause")
SOUND:LoopBattleSE("EVT_Applause")
SOUND:StopSE("Battle/EVT_Applause")
SOUND:StopBattleSE("EVT_Applause")

The sound effect must use LOOPSTART/LOOPLENGTH tags to loop properly.

Change the name of the character? (Stub)

GAME:SetCharacterNickname(partner, result)

Change the starters?

Go to Data/StartParams.xml. Edit the contents of the StartChars tag. They represent which species number you’re allowed to start as:

  <StartChar>
    <Species>1</Species>
    <Form>0</Form>
    <Skin>0</Skin>
    <Gender>Unknown</Gender>
    <Name/>
  </StartChar>

You can also alter form, skin (shinyness), gender and a preset name. If there is only one choice, with a preset name, the starting menu will be skipped entirely. This is the preferred way to start Explorers of Sky-type Special Episodes.

Make a character say something different when talked to again?

You will need to edit Data/Script/scriptvars.lua. Add an additional table with a single variable like below:

SV.your_map_name =
{
  TalkedToNpc  = false
}

If there already exists a table with your map name on it, just add the variable to it. Then, add a check to your NPC’s action event:

function your_map_name.YourNpc_Action(chara, activator)
    if SV.your_map_name then
        UI:WaitShowDialogue(STRINGS:Format(MapStrings['String_002']))
    else
        UI:WaitShowDialogue(STRINGS:Format(MapStrings['String_001']))
        SV.your_map_name = true
    end
end

Make a character say the player's name? (Stub)

UI:WaitShowDialogue(STRINGS:Format(MapStrings['String_001'], player:GetDisplayName()))

String: Hello, Are you {0}, right?

This one replaces {0} with the player's name and colored blue.

Move the camera?

To an absolute position, X40 Y40:

GAME:MoveCamera(40, 40, 1, false)

To a position relative to the player, 80 pixels above player:

GAME:MoveCamera(0, -80, 1, true)

Move slowly over the course of 60 frames:

GAME:MoveCamera(40, 40, 60, false)

Show a Pre-Drawn Picture?

UI:WaitShowBG("Sky", 1, 20);
UI:WaitInput(false);
UI:WaitHideBG(20);

This snippet fades in the Sky background in 20 frames, waits for input, and fades it out on input.

Set the map weather?

GROUND:AddMapStatus(6)

This call will add Map Status #6, which is Cloudy weather. To make the map start with this status, place it in the Init function of the map.

Other unexplained codes that has yet to provide more info.

GAME:EnterDungeon('tropical_path', 0, 0, 0, RogueEssence.Data.GameProgress.DungeonStakes.Risk, true, true)
GAME:EnterGroundMap("base_camp_2", "entrance_west")