Variables

Variables vs Game State Props

You can directly access and set Props in the Game State using GET_PROP and SET_PROP, so you might be wondering why how variables are different from Props. There are a few differences:

  1. Props (and the entired game state) are persistent and can be accessed by other players and the frontend, whereas variables only exist during execution of receivers and are thrown away at the end of execution
  2. When you define a function, the arguments for that function automatically create function scope variables (not props) that only exist during the execution of that function.
  3. There are two special variables that are the only global variables in LudL.

Naming and Assignment

  • Variable names must only use alphanumeric characters
  • By convention, variable names should only use lower case
  • $var_name (with the special symbol $) is used to evaluate the variable and for function definitions
  • To set a variable value, use the primitive ASSIGN and a string literal for the variable name, e.g.:
ASSIGN 'tmp' 1;
# returns 1
DEBUG $tmp;

But NOT

# this will not parse
ASSIGN $tmp 1;

Special Variables

  • special variables cannot be assigned, only evaluated
  • special variables are global in scope (can be accessed from inside any function call no matter how nested)
$CURRENT_PLAYER

This is equal to the first element of the PROP play_order

$PLAYER_NAME

This is equal to the player name of the user that sent the message.

For example, in a game of chess, user garfield has assumed the role of white and user jackson has assumed the role of black. When garfield makes a move, the frontend will send a message like move_token Pw4 e4 to the backened, triggering execution of the RECEIVE move_token $a $b: directive. During this execution, $PLAYER_NAME will evaluate to 'white'. During execution of messages received from jackson, $PLAYER_NAME will evaluate to 'black'.

$PLAYER_NAME will always match to one of the values defined in the play_order prop.

Data Types

Variables can be one of the following types:

BOOL
INT
FLOAT
STRING
NUMBER

INT | FLOAT

COMPARABLE

NUMBER | STRING

LIST

structures indexed by consecutive integers starting at 0

DICT

structures indexed by strings

TUPLE

similar to a list, but the length is fixed

NULL
TOKEN

a data structure corresponding to tokens in the game state. Tokens have props that can be accessed via TOKEN_GET_PROP and TOKEN_SET_PROP

See also TOKEN.

CONTAINER

a data structure corresponding to containers in the game state. Containers have props that can be accessed via CONTAINER_GET_PROP and CONTAINER_SET_PROP as well as contents that can be accessed via APPEND, POP, POP_BY_NAME, GET_BY_POSITION.

See also CONTAINER.

ANY

any of the above