Skip to content

All commands list

This page lists all available narrat commands as well as usage examples.

Dialog

CommandExampleDescription
talktalk player idle "Hello everyone"Makes a character talk in a specific pose
thinkthink player idle "I wonder if they like me"Makes a character think in a specific pose (think is the same as talk but without quotes around)
text command (Empty command)"Hello world"Writing text without a command will print that text as if it was said "by the game", without a character

Basic program flow

CommandExampleDescription
jumpjump myLabelJumps to a label (stops current script)
runrun myLabel [arg1] [arg2] [...] // Returns whatever the label returned, if anythingRuns a label as a function with optional arguments passed to it, then continues back where the script was
returnreturn $testReturns a value. Exits the current label and returns the first argument
ifif $data.hasFood:"I have food, so we can eat a meal!"else:"We have nothing to eat"Runs a condition on the passed value. If the condition is true, the first branch is run. Otherwise, an optional else: branch can be provided for what to run when the condition fails

Choices

CommandExampleDescription
choicechoice:"Would you like tea?""Yes":"Your friend serves you a cup of tea""No":"Your friend makes tea for themselves"Lets the player choose between two or more options. See the linked documentation for more info.
text_fieldtext_field "A prompt text"Creates a text field for the player to enter text with a prompt. Returns the text entered

Logic operators and conditions

CommandExampleDescription
== ,>, <, <=, >=, !=== 5 5 // Returns trueComparison operators to check if things are equal/unequal/lower than/etc
!if (! $data.doorOpen):"The door is closed"Negates a value
&&, ||if (|| $data.doorOpen $data.hasKey):And and Or logical operators
?var isDead (? (<= $data.life 0) true : false)Ternary operator

Math and arithmetic

CommandExampleDescription
++ 1 2 // Returns 3Adds numbers passed as arguments
-- 2 1 // Returns 1Substracts the first number passed with the others
** 2 3 // Returns 6Multiplies the numbers together
// 1 2 // Returns 0.5Divides the first number by the others, in sequence
minmin 100 50 // Returns 50Returns the smallest value passed
maxmax 50 100 // Returns 100Returns the highest value passed
clampclamp 0 100 $data.playerHealth If playerHealth is below 0, return 0. If playerHealth is between 0 and 100, returns it. If playerHealth is over 100, returns 100Returns the third value passed, constrained between a minimum and maximum value passed as the first two parameters
floorfloor 0.75 // Returns 0Rounds a number, rounding down
ceilceil 0.25 // Returns 1Rounds a number, rounding up
roundround 0.5 // Returns 1Rounds a number to the nearest integer
sqrtsqrt 4 // Returns 2Returns the square root of a number
^^ 3 2 // Returns 9Returns the first number to the power of the second number

Audio

CommandExampleDescription
playplay music myMusic [channel]Plays the music myMusic in the mode music (possible modes: music, ambiance, sound), with an optional channel number
pausepause music [channel]Pauses a music mode with an optional channel number
[resume]((audio/pause.md) /resume.md)resume music [channel]Resumes a music mode with an optional channel number
stopstop music [channel]Same as pause but stops

Items

CommandExampleDescription
add_itemadd_item bread 1Adds an amount of an item to the player
remove_itemremove_item bread 1Removes an amount of an item
has_item?if (has_item? bread 1):"Let's eat bread!"Returns true if there is enough of the item
item_amount?item_amount? bread // returns the amount of breadReturns the amount of an item the player has
enable_interactionenable_interaction mytagEnables an interaction tag (see docs)
disable_interactiondisable_interaction mytagDisables an interaction tag (see docs)

Achievements

CommandExampleDescription
unlock_achievementunlock_achievement win_gameUnlocks an achievement
has_achievement?set data.hasWon (has_achievement? win_game)Returns true if the player has the passed achievement, otherwise false

Notifications

CommandExampleDescription
notifynotify "Hello world"Adds a notification to the game
disable_notificationsdisable_notificationsDisables all notifications
enable_notificationsenable_notificationsEnables notifications

Quests

CommandExampleDescription
start_queststart_quest myQuestStarts a quest
complete_questcomplete_quest myQuestCompletes a quest
[`start_objective`](../features/quests.md)start_objective myQuest myObjectiveStarts an objective in a quest (useful for quests with hidden objectives)
complete_objectivecomplete_objective myQuest myObjectiveCompletes an objective
quest_completed?quest_completed? myQuest // returns true or falseCheck if a quest is completed
objective_completed?objective_completed? myQuest myObjective //returns true or falseCheck if a quest objective is completed
quest_started?quest_started? myQuest // Returns true or falseCheck if a quest is started
objective_started?objective_started? myQuest myObjective // Returns true or falseCheck if a quest objective is started

Random

CommandExampleDescription
randomrandom 0 100 // Returns a random integer between 0 and 100 Returns a random integer between two numbers passed (inclusive)
random_floatrandom_float 0 100 // Returns a random float between 0 and 100 Returns a random float between two numbers passed (inclusive)
random_from_argsrandom_from_args 1 2 3 4 5 // Returns a random argument passed Returns a random argument passed
random_from_arrayrandom_from_array $data.myArray // Returns a random element from the arrayReturns a random element from an array

Viewport screen and buttons

CommandExampleDescription
set_screenset_screen myScreen [layer]Sets the screen to a screen with the given ID with an optional layer number (default 0)
empty_layerempty_layer 0Removes all items from a layer
set_buttonset_button myButton truechanges the value of a button (true, false, hidden) ID

Variables

CommandExampleDescription
setset data.playerHealth 100Sets a variable to a value
addadd data.playerHealth 10Adds a value to a variable
varvar test 3Declares a local variable with a value. The variable will only exist in the current label and will stop existing once the label is exited.

Skills

CommandExampleDescription
add_leveladd_level agility 1Adds levels to a skill
set_levelset_level agility 1Sets the level of a skill
add_xpadd_xp agility 10Adds experience to a skill
get_levelget_level agilityGets the level of a skill
get_xpget_xp agilityGets the experience of a skill
rollroll mySkillCheck agility 50 // Returns true or falseRuns a skill check with a certain difficulty against a skill dice
get_skill_checkget_skill_check mySkillCheck // Returns a skill check's stateGets the result of a skill check (object with happened, succeeded, and hidden booleans)
skill_check_resultskill_check_result mySkillCheck // Returns true or falseGets the result of a skill check as boolean
reset_rollreset_roll mySkillCheckResets a skill check

Stats

CommandExampleDescription
add_statadd_stat myStat 10Adds a value to a stat
set_statset_stat myStat 10Sets a stat to a value
get_stat_valueget_stat_value myStatGets the value of a stat
show_hudshow_hudShows the HUD
hide_hudhide_hudHides the HUD

Arrays

Imagine $data.myArray contains an array with [25, 50, 75]

CommandExampleDescription
newset data.myArray (new Array)Creates an array
pushpush $data.myArray 100Adds a value at the end of an array
poppop $data.myArray // Returns 100Removes the last value of an array, returning it
shiftshift $data.myArray // Returns 25Removes the first value of an array, returning it
array_joinarray_join $data.myArray ", " // Returns "25, 50, 75"Joins an array into a string, with the first parameter being the separator to use
array_concatarray_concat $data.myArray $data.myArray2 // Returns [25, 50, 75, 100, 125]Concatenates two arrays
includesincludes $data.myArray 25 // Returns trueChecks if an array includes a value
reversereverse $data.myArray // Returns [75, 50, 25]Reverses an array
sliceslice $data.myArray 1 2 // Returns [50, 75] Returns a slice of an array, with the first parameter being the start index and the second being the end index
splicesplice $data.myArray 1 2 // Returns [50, 75]Removes a slice of an array, with the first parameter being the start index and the second being the number of elements to remove. Returns the sliced elements
random_from_arrayrandom_from_array $data.myArray // Returns a random element from the arrayReturns a random element from an array
shuffleshuffle $data.myArray // Returns a shuffled arrayShuffles an array
entriesentries $data.myArray // Returns [[0, 25], [1, 50], [2, 75]]Returns an array of arrays, each containing the index and value of the original array's elements

Array transformation functions

Those functions loop through arrays to perform an operation on each element. Most of them take a predicate parameter, which should be the name of a narrat label that will be called on each element.

The predicate gets given three parameters:

  • element: The array element for the current iteration
  • index: The index of the current iteration
  • array: The array being iterated over

Some of those functions may take different parameters though.

Example:

narrat
test_arrays:
  var simple (new Array "a" "b" "c" "d")
  var index (array_find_index $simple test_find)
  "Index: %{$index}"
  var mapped_array (array_map $simple test_map)
  var concatenated (array_join $mapped_array ", ")
  "Concatenated: %{$concatenated}"

test_forEach element index array:
  "For each: %{$element} %{$index} %{$array}"

test_find element index array:
  if (== $element "c"):
    return true
  else:
    return false

test_map element index array:
  return (concat $element " mapped")

Most of those functions have an API based on similar JavaScript equivalents, which you can find on the MDN documentation.

CommandExampleDescription
array_find_indexvar index (array_find_index $array test_find)Will run the test_find label with values passed from the array until it returns true, at which point it will return that index. If nothing is found, it will return -1
array_findvar element (array_find $array test_find)Will run the test_find label with values passed from the array until it returns true, at which point it will return that element. If nothing is found, it will return null
array_filtervar filtered (array_filter $array test_filter)Will run the test_filter label with values passed from the array. Every element for which test_filter returns true will be added to the new result array that gets returned at the end
array_mapvar mapped (array_map $array test_map)Will run the test_map label with values passed from the array. A new resulting array is created which gets as values the return values of test_map passed for each element
array_reducevar reduced (array_reduce $array test_reduce 0)Will run the test_reduce label with values passed from the array. Before the element, index and array parameters the test_reduce function will reduce the current accumulated reduced value, starting with the initial value passed in the initial call (0 here)
array_somevar some (array_some $array test_some)Will run the test_some label with values passed from the array. If any of the calls to test_some return true, the function will return true. If none of them do, it will return false
array_everyvar every (array_every $array test_every)Will run the test_every label with values passed from the array. If all of the calls to test_every return true, the function will return true. If any of them don't, it will return false

Object Commands

imagine we have the following object:

narrat
main:
  var test_object (new Object)
  set test_object.a "hello"
  set test_object.b "world"
CommandExampleDescription
object_keysvar keys (object_keys $array)Returns an array with the keys in the object. In this case would return ["a", "b"]
object_valuesvar values (object_values $array)Returns an array with the values in the object. In this case would return ["hello", "world"]
object_entriesvar entries (object_entries $array)Returns an array with the entries in the object. In this case would return [["a", "hello"], ["b", "world"]]
object_hasvar has (object_has $array "a")Returns true if the object has the given key, false otherwise

For loop commands

Narrat doesn't have proper support for loops yet, but those two commands can help give similar functionality (they work on both arrays and objects).

Imagine we have the following test array:

narrat
main:
  var test_array (new Array "a" "b" "c" "d")

do_things element:
  "Element: %{$element}"
CommandExampleDescription
for_offor_of $test_array do_thingsWill run the do_things label once for each element in the array, passing the element as the first property. This one iterates over values
for_infor_in $test_array do_thingsWill run the do_things label once for each element in the array, passing the index (or key if an object) as the first property. This one iterates over keys

Time

CommandExampleDescription
time_nowvar now (time_now) // returns current time in msReturns the current unix timestamp in miliseconds
total_playtimevar time_played (total_playtime)Returns the current total playtime for this save file
session_playtimevar time_played (session_playtime)Returns the current session playtime
to_daysvar days (to_days 100000)Converts a time in ms to days
to_hoursvar hours (to_hours 100000)Converts a time in ms to hours
to_minutesvar minutes (to_minutes 100000)Converts a time in ms to minutes
to_secondsvar seconds (to_seconds 100000)Converts a time in ms to seconds

Strings

CommandExampleDescription
concatconcat "Hello" "World"Concatenates two or more strings
joinjoin ", " "Hello" "World"Joins x strings, with the first character being the join string between them

Screen Objects

See Dynamic sprites and text documentation for info on how to use screen objects.

CommandExampleDescription
create_spritecreate_sprite img/character.png 55 125Creates a sprite using an image at a position
create_objectcreate_object 55 125Creates an object at a position
delete_spritedelete_sprite $mySpriteDeletes a sprite (stored in a variable)
empty_spritesempty_sprites [optional layer number]Deletes all sprites, on specified layer or all layers if no layer is passed

Characters

It is possible to change which character is used by the player (which is used when making choices). See the changing player character feature docs for more info.

CommandExampleDescription
change_player_characterchange_player_character player_2Will use player_2 as the character for the player's words in choices etc.
change_game_characterchange_game_character game_2Changes the default character used to represent the game (by default is a character with no name)

Others

commandexampledescription
clear_dialogclear_dialogClears the dialog panel
loglog "what's the value of test? %{test}" // Will print this log in the consolePrints a log in the browser developer tools. Useful for debugging or checking variable values
menu_returnmenu_returnExits the game and returns to the main menu
savesave [save file name]Opens the manual save screen for the player to save the game (optional parameter for the name of the save file, useful to pass the name of the level/chapter for example)
reset_global_savereset_global_saveResets the global part of the save
save_promptsave_prompt [save file name]Same as save, but asks the user if they want to save first
waitwait 500Makes the script pause for x milliseconds
load_dataset data.myData (load_data data/myDataFile.yaml)Loads data from the data file path passed and returns it

Released under the MIT License.