Primitives

A primitive is a basic operation. They are the lowest level function, and all other functions are built on top of them.

Note

Unlike user defined functions, primitives are typed. The input must match the type given here.

Like all other functions, primitives accept a fixed number of arguments. There is no such thing as an optional argument in the LudL language.

Primitives on basic data types

NOT
Parameters:
  • val (BOOL) – input expression
Returns:

logical NOT of the input

Sample usage:

# returns the not of $a, if $a is storing a BOOL
NOT $a;
# returns !(a&&b)
NOT AND $a $b;
AND
Parameters:
Returns:

logical AND of the inputs
OR
Parameters:
Returns:

logical OR of the inputs
CONCAT
Parameters:
Returns:

concatenation of two strings

Sample usage:

# returns the string 'abc123'
CONCAT 'abc' '123';
PLUS
Parameters:
Returns:

sum of two numbers

Sample usage:

# returns 3
PLUS 1 2;
# decrements the variable i by 1
ASSIGN 'i' PLUS $i -1;
MINUS
Parameters:
Returns:

val1 - val2
MULT
Parameters:
Returns:

product of two numbers
DIVIDE
Parameters:
Returns:

val1 / val2
ABS
Parameters:
Returns:

absolute value of a number
EQUAL
Parameters:
  • val1 (ANY) –
  • val2 (ANY) –
Returns:

tests whether two values are equal to each other

Sample usage:

# returns true
EQUAL 2 PLUS 1 1;
# returns false
EQUAL 1 'lol?';
LESS
Parameters:
Returns:

tests whether one value is strictly less than another
GREATER
Parameters:
Returns:

tests whether one value is strictly greater than another
LESS_OR_EQUAL
Parameters:
Returns:

tests whether one value is less than or equal to another
GREATER_OR_EQUAL
Parameters:
Returns:

tests whether one value is greater than or equal to another
TUPLE2
Parameters:
  • val1 (ANY) –
  • val2 (ANY) –
Returns:

a 2-tuple consisting of the input values

Sample usage:

# the variable x now has the value (1, 'abc')
ASSIGN 'x' TUPLE 1 'abc';
IS_NULL
Parameters:
  • val (ANY) –
Returns:

tests whether a value evaluates to NULL
STR
Parameters:
  • val (ANY) –
Returns:

casts the input to a STRING
INT
Parameters:
  • val (ANY) –
Returns:

casts the input to a INT
FLOAT
Parameters:
  • val (ANY) –
Returns:

casts the input to a FLOAT
SIZE
Parameters:
Returns:

how many elements the object contains
NULL
Returns:the value NULL (type NULL)
TRUE
Returns:the value TRUE (type BOOLEAN)
FALSE
Returns:the value FALSE (type BOOLEAN)
EMPTY_LIST
Returns:the empty list ([]) (type LIST)

Primitives on Game State (getters/setters)

GET_CONTAINER
Parameters:
Returns:

the CONTAINER indexed by container_name. If no such container exists, returns NULL.
GET_TOKEN
Parameters:
Returns:

the TOKEN indexed by token_name, no matter which CONTAINER it belongs to. If no such token exists, returns NULL.
GET_TOKEN_AND_LOCATION
Parameters:
Returns:

finds the TOKEN indexed by token_name, no matter which CONTAINER it belongs to. Additionally returns the container that the token belongs to. The results are returned as a TUPLE2 (token, container).
GET_PROP
Parameters:
Returns:

the PROP indexed by prop_name. If no such prop exists, returns NULL.
TOKEN_GET_PROP
Parameters:
Returns:

the prop indexed by prop_name on a given TOKEN. If no such prop exists for that token, returns NULL.
CONTAINER_GET_PROP
Parameters:
Returns:

the prop indexed by prop_name on a given CONTAINER. If no such prop exists for that container, returns NULL.
SET_PROP
Parameters:
Returns:

nothing. Set a given prop to a given value

Sample usage:

# probably returns NULL
GET_PROP 'random_prop_that_probably_doesnt_exist';
# returns 1
SET_PROP 'random_prop_that_probably_doesnt_exist' 1;
GET_PROP 'random_prop_that_probably_doesnt_exist';
TOKEN_SET_PROP
Parameters:
Returns:

nothing. Set a given prop on a given token to a given value

Sample usage:

# doesn't work, first argument needs to be the token, not name of the token
TOKEN_SET_PROP 'Pw4' 'piece-color' 'black';
# returns white (this is a white pawn)
TOKEN_GET_PROP GET_TOKEN 'Pw4' 'piece-color';
ASSIGN 'tmp_token' GET_TOKEN 'Pw4';
SET_PROP $tmp_token 'piece-color 'black;
# this pawn has been subverted to the black player
TOKEN_GET_PROP GET_TOKEN 'Pw4' 'piece-color';
CONTAINER_SET_PROP
Parameters:
  • container –
  • prop_name (STRING) –
  • val (ANY) –
Returns:

nothing. Set a given prop on a given container to a given
ROTATE_PLAY_ORDER
Returns:nothing. Rotate the special PROP play_order, which is used to determine CURRENT_PLAYER and the special prop current_player. Rotate means the first element is removed and appended in the last position. The relative ordering for the other elements is not changed.

Sample usage:

# a player takes his turn
ROTATE_PLAY_ORDER;
# now the next player is $CURRENT_PLAYER
DUPLICATE_TOKEN
Parameters:
Returns:

creates a duplicate of the input token (all props will be the same except for name, which will be auto set so as to be distinct from all existing tokens) and returns it.

Primitives on CONTAINERs

GET_BY_POSITION
Parameters:
Returns:

return the i th token from the given container

Sample usage:

# if this is called at the beginning of a chess game, should return the pawn at position 'e2', name 'Pw4'
GET_BY_POSITION GET_CONTAINER 'e2' 0;
CONTAINS_BY_NAME
Parameters:
Returns:

return whether the given container contains a token with the given name

Sample usage:

# if this is called at the beginning of a chess game, should return TRUE
CONTAINS_BY_NAME GET_CONTAINER 'e2' GET_TOKEN 'Pw4;
# FALSE, there is not a black rook at e2 (at any position)
CONTAINS_BY_NAME GET_CONTAINER 'e2' GET_TOKEN 'Rb0;
POP
Parameters:
Returns:

remove the token at position i and return it. If the container has less than i children, returns NULL.

Sample usage:

# take the pawn 'Pw4' off 'e2'. Now it is ready to be placed somewhere else
ASSIGN 'tmp_token' POP GET_CONTAINER 'e2' 0;
POP_BY_NAME
Parameters:
Returns:

if the container contains a token with name token_name, remove it from the container and return it. Otherwise, return NULL.
SHUFFLE
Parameters:
Returns:

shuffles the contents of the container, then returns that container.

Primitives on container types (lists, dicts, tuples)

REVERSE
Parameters:
Returns:

reverse the input list in place, then return it.
SORT
Parameters:
Returns:

sort the input list in place (ascending order), then return it.
SORT_TUPLE
Parameters:
Returns:

input list is assumed to be a list of TUPLE2s. Sort the input list based on the second element in the tuple, then return it.
GET_ELT
Parameters:
Returns:

returns the value indexed by key in the given DICT.
SET_ELT
Parameters:
Returns:

set the value indexed by key in the given DICT to the given value.
GET_POSITION_ELT
Parameters:
Returns:

returns the value at the i th position in the given input value.
SET_POSITION_ELT
Parameters:
Returns:

set the value at the ``i``the position in the given LIST to the given value.
APPEND
Parameters:
Returns:

nothing. Append the given value to the given container. If container is a CONTAINER, val should be a TOKEN.
PREPEND
Parameters:
Returns:

nothing. Prepend the given value to the given container. If container is a CONTAINER, val should be a TOKEN.
MAP
Parameters:
Returns:

apply the function given by func_name to every element of the list and store the results, in order, in a new list, and return that list.

Note

The function given by func_name must take only one argument

Misc primitives

ASSIGN
Parameters:
  • var_name (STRING) – name of the variable
  • var_val (ANY) – value to assign to the variable
Returns:

NULL

Sample usage:

ASSIGN 'tmp' 1;
# returns 1
DEBUG STR $tmp;
RETURN
Parameters:
  • val (ANY) – value
Returns:

Immediately exit the function returning the value indicated by val, can only be used inside Functions.

Note

RETURN must take an argument. RETURN; is not a valid statement, you’ll need something like RETURN NULL;

ACCEPT
Returns:Immediately exit the receiver directive returning nothing and send an “ACCEPT” message to the frontend (meaning the received message was a legal move). Can only be used inside Receivers
REJECT
Parameters:
Returns:

Immediately exit the receiver directive and send a “REJECT” message to the frontend (meaning the received message was an illegal move). This message contains val as part of the payload, and it should explain the reason for rejecting the move. Can only be used inside Receivers
DEBUG
Parameters:
Returns:

Log a debug message. When execution stops (via ACCEPT/REJECT), the log of all debug messages encountered during execution is sent back to the frontend.
INSTANTIATE_TOKEN
Parameters:
  • tokenset_id (INT) –
  • token_prototype_name (STRING) –
  • num_copies (INT) – how many copies of the token to make
  • target_container_name (STRING) –
Returns:

Instatiates tokens in the game state according to the specified token prototype. The instatiated tokens are placed into a container with the specified name. The names of the instantiated tokens are a concatenation of the token prototype name with an integer to preserve uniqueness. Returns nothing (NULL).

Sample usage:

INSTANTIATE_TOKEN 123 bird 2 bird_nest

This finds the token prototype named bird from tokenset id#123, creates 2 copies and places them into the container named bird_nest in the game state (if it exists). The tokens will be named something like bird0 and bird1.

Note

This primitive should only be called from inside the set_up definition. Other functions won’t have access to token prototypes in their execution environment.

INSTANTIATE_ALL_TOKENS
Parameters:
  • tokenset_id (INT) –
  • target_container_name (STRING) –
Returns:

Instatiates all tokens from the given tokenset into the game state. The instatiated tokens are placed into a container with the specified name. Returns nothing (NULL).
RANDOM_INT
Parameters:
  • max_range –
Returns:

A random integer from the range [0, max_int] inclusive.