Language reference - lamarr-lang/lamarr-lang.github.io GitHub Wiki

Code structure

The code consists of sections and global commands (outside of a section). Section starts with header and ends with empty line.

item "Key" "There is a key on the desk."       <-- this is header
  pick "You put the key in your pocket."       <-- section line (indent recommended)
  use "You used the key... nothing happened."  <-- another section line
                                               <-- empty line (end of section)
var x:= 0                                      <-- global command

Compatibility

All keywords are case-sensitive, it is recommended not to exceed 32 chars for identifiers and 1024 chars for strings. The source code should be saved in UTF-8.

Comments

Comments are single line starting with #.

Multiline comments starts with heading #| and ends with trailing |#.

Strings

Strings are in quotes: Multiword text mentioned to be displayed. There are two special chars in strings: | (alternative) and ~ (variable).

"You are normal ~age years old guy.|You feel old.|You are who you are."

Random part separated by | is displayed. ~age is sibstitued by variable identified as age.

Global commands

start

start "Welcome to the game. Play or die!" arena

• STR32 start keyword (must be exacty one in the game)
• STR1024 "string" welcome message to the game
• STR32 node The starting text node

title

title "Demo game"

• STR32 title keyword
• STR64 "string" title of the game

version

version 1.2

• STR32 version keyword
• STR32+ id version id. Chars "." and ":" are allowed

node

node [final] nodeName "Node description"

• STR32 node keyword
• STR32 final keyword means final node (game over)
• STR32 nodeName unique node identifier
• STR1024 "string" Node description.

Example

node arena "You've came into the arena. The crowds are cheering."

var

Declares and defines a variable. For time being, variables can contain integers only.

Syntax

var varName:= number|range|anotherVar

• var keyword
• STR32 varName unique variable identifier
• := assign operator
• INT32 number is an integer constant
• STR32 range is in format i.e. 1 to 6 (spaces around dash possible, pick a random number from 1 to 6 inclusive)
• STR32 anotherVar is another variable (copied by value)

Example

var strength := 13 to 18

If non-declared variable is used, no error is generated, the variable is auto-created on the first use and assigned to 0.

property

Defines property, which is displayed next to player's options.

Syntax

property varName "show" [range]

• property keyword
• STR32 varName (private) variable used for the property
• STR32 "show" what to show next to the players options
• STR32 range keep the variable in that range

example

property strength "Current strength" 1 to 21

Output: Current strength(17)

action

Defines action performable besides pick / check / use / lay items actions.

Syntax

action nodeName|cond "description" "message"|modName

• action keyword
• STR32 nodeName action is available at that node - equivalent to (atnode nodeName) condition
• STR512 cond action is available if the condition is satisfied
• STR64 "description" action description
• STR1024 "message" displayed after the action is performed
• STR32 modName mod run at the action

Example

action vez "Vykouknout z věže" "Vykouknul jsi z věže."

path

Describes path from node to node. Every path is one-way! Syntax

path fromNode "Description" toNode [modName]

• STR32 fromNode unique node identifier; node which the player wishes to leave
• STR64 "Description" used as "Go" option. The first big letter is used as activating key and must be unique in node "Go" option.
• STR32 toNode unique node identifier; the destination of player's movement
• optional STR32 modName unique mod identifier; mod which is executed on the movement; there is a special mod move which (if exists) is executed on every move

pick, check, use, lay

Globally used item action. Details are described in item action, except in the global form item name immediatelly follows action keyword.

Syntax

  [ [first [count]] pick [no] itemName [(cond)] "textMod"|modName ]...
  [ [first [count]] check itemName [(cond)] "textMod"|modName ]...
  [ [first [count]] use itemName [on target] [(cond)] "textMod"|modName ]...
  [ [first [count]] lay [no] itemName [(cond)] "textMod"|modName ]...

• STR32 itemName item identifier on which the action is performed.

section nodes

Summary syntax for nodes.

Example

nodes
  bathroom "You are in bathroom."
  hall "You are in hall."
  final livingroom "You are in living room."

section vars

Summary syntax for vars. Example

vars
  strength:= 13 to 17
  dexterity:= 9 to 11
  resistance:= 12 to 16

section properties

Summary syntax for properties.

Example

properties
  strength "Strength" 1 to 21
  dexterity "Dexterity" 1 to 21
  resistance "Resistance" 1 to 21

section actions

Summary syntax for action.

Example

actions
  vez "Vykouknout z věže" "Vykouknul jsi z věže."
  (atnode vchod, var odhaleno=1) "Zaklepat na dveře" zaklepani

section map

Summary syntax for paths. Keyword paths is an alternative (map is deprecated).

Example

map
  room "Out" corridor wentOut
  corridor "Room" room
  corridor "Hall" hall

section item

Describes an item in the game: where it is located, how it can be picked, checked, used or layed.

Syntax

item name "sign" ["appendix"]
  [ location no|nodeName|player ]
  [ resource[s] nodeName [,...] ]
  [ [first [count]] pick [no] [(cond)] "textMod"|modName ]...
  [ [first [count]] check [(cond)] "textMod"|modName ]...
  [ [first [count]] use [on target] [(cond)] "textMod"|modName ]...
  [ [first [count]] lay [(cond)] "textMod"|modName ]...
  [ pick [no]|check|use|lay boring ]...
  [ boring pick|pick no|check|use|lay [,...] ]

• STR32 name unique item identifier
• STR64 "sign" what is displayed to the player in item actions
• STR1024 "appendix" what is appended to the node description if the item lays there

location

If location is ommited, it is placed into player's inventory.

• location keyword
• no keyword means that item is not located anywhere (can be placed by mod command additem)
• STR32 nodeName places the item to the node
• player keyword places the item into player's inventory.

resource (or resources)

Resource item is not removed from node if player takes it.

• ** resource** keyword
• STR32 nodeName nodes, where the item will be available as resource.

check

If check is omitted, the item is not displayed as a subject to check. Besides of that, any item in the player's inventory or in the node with the player can be checked.

• first keyword applies the mod only on the first check
• INT32 count if not ommited, applies the mod only on the first count checks
• check keyword
• STR512 (cond) mod is run only if the condition is satisfied
• STR1024 "textMod" a mod is created; it displays the message
• STR32 modName a mod is associated with this action

There can be multiple check statements. The last satisfying command is used, but the cond statements, if satisfied, have higher priority and keyword first has even higher priority than cond.

lay

If lay is omitted, the player can't get rid of that item (unless by mod command delitem). Besides of that, any item in the player's inventory can be returned in some node. The meaning of other commands is as described in check.

pick

If pick is ommited, the item can't be picked.

• no keyword leaves the item in the node on pick attempt, but still runs the mod
• STR1024 "textMod" also places the item into player's inventory (unless no keyword was used)

The meaning of other commands is as described in check.

use

If use is ommited, the item can't be used. Only items in player's inventory can be used.

• on keyword uses the item on some other item placed in player's inventory or in the node where the player is located.

The meaning of other commands is as described in check. The on priority is higher than first priority.

boring

The boring section provides enables the action and provides the default textMod for that.

Example (summary syntax):

item key "Key"
  boring pick,check,use,lay
  use on doors (atnode room) unlockDoors

Example (per action syntax):

item key "Key"
  pick boring
  check boring
  use boring
  use on doors (atnode room) unlockDoors
  lay boring

section boring

Defines custom default messages for boring item actions. Tilde (~) is substituted for item name.

boring
  pick "You picked the ~."
  pick no "You can't pick the ~."
  check "You checked the ~ and found nothing unusual."

section mod

Mod is an action invoked by item pick, check, use or lay or by traversing node. Syntax

mod modName
  [ [(called <|>|= count)] message "description"]...
  [ [(called <|>|= count)] additem nodeName itemName]...
  [ [(called <|>|= count)] additem itemName]...
  [ [(called <|>|= count)] delitem itemName]...
  [ [(called <|>|= count)] setitem itemName "itemSign" ["itemAppendix"] ]...
  [ [(called <|>|= count)] addresource itemName nodeName]...
  [ [(called <|>|= count)] delresource itemName nodeName]...
  [ [(called <|>|= count)] setnode nodeName "description"]...
  [ [(called <|>|= count)] addpath fromNode "description" toNode]...
  [ [(called <|>|= count)] delpath fromNode toNode]...
  [ [(called <|>|= count)] teleport node]...
  [ [(called <|>|= count)] var varName :=|+=|-=|*= value[/divider|-range] ]...
  [ [(called <|>|= count)] callmod modName]...
  [ [(called <|>|= count)] skip linesCount]...
  [ [(called <|>|= count)] return]

called

Command is executed only if mod was called maximum / at least / exactly (depends on operator) INT32 count times.

message

Displays text and waits for keypress, then clears the screen.

• STR1024 "description" text to be displayed

additem

Adds item to player's inventory or node.

• STR32 nodeName where the item will be added. If ommited, the item will be added into player's inventory.
• STR32 itemName id of that item

delitem

Removes item from player's inventory or node.

• STR32 itemName id of item to be removed

setitem

Sets the item sign and description.

• STR32 itemName id of the item to be set
• STR64 "sign" new sign of that item
• STR1024 "description" new description of that item

addresource

Adds resource to node. Resources are in its node if player picks some of it as an item.

• STR32 itemName item id of the resource.
• STR32 nodeName where the resource will be added.

delresource

Removes resource from node.

• STR32 itemName item id of the resource.
• STR32 nodeName where the resource will be removed.

setnode

Sets node description.

• STR32 nodeName id of the the node to be set
• STR1024 "description" new node description

addpath

Adds oneway path connection between nodes

• STR32 fromNode starting node of the path
• STR64 "description" description of the path. The first big letter will be used as the activating key.
• STR32 toNode ending node of the path

delpath

Removes oneway path connection between nodes

• STR32 fromNode starting node of the path
• STR32 toNode ending node of the path

teleport

Teleports player to any node

• STR32 node node id of the destination

var

Alters variable.

• var keyword
• STR32 varName id of the variable
• STR2 := | += | -= | *= assign | increase | decrease | multiply operator. The rest of the command is RHS (right hand side) and can come in one of the following forms:

var rhs

RHS can contain var names. It is always copied by value by the time of call.

• value - the RHS is this value
• value/divider - the RHS is this fraction. The result is converted to integer (fraction part is discarded)
• value-range - the RHS is any number between value and range (inclusive). Range has to be greater than value.

** Examples **

var x:= 2
var y := 7/x # y is 3
var z :=1-y # z is 1 or 2 or 3
var y+= 6 /z # y is 9 or 6 or 5
var u:= 9
var u*= 1/x # u is 4 

Conditions

Conditions are written inline in brackets see (cond) above. Members are separated with comma, condition is satisfied if all members are satisfied.

Syntax

([atnode [no] nodeName] [,...] [, hasitem [no] itemName] [,...]
[, var varName <|>|= value] [,...] [, number%])

atnode

• STR32 nodeName cond is satisfied if player is (or is not if no is prepended) in that node.

hasitem

• STR32 itemName cond is satisfied if player has (or has not if no is prepended) specified item in his inventory.

var

• STR32 or INT32 value test specified value. RHS can be integer constant or variable

%

• INT32 condition is satisfied with probability (i.e. 25%)

Saving

The save file has .txgs suffix, the filename is the same as the game. The data are in UTF-8, numbers are saved as digits, strings are shifted one position right in the UTF-8 chart ("Hello" is saved as "Ifmmp").

The first 31 characters in UTF-8 table are non-printable special chars with this meaning:

• separators* 1,2,3
• members 4,5,6,7,8 (supports 100+ member types in entity)
• entities 9-25 (so far node=9, item=10, action=11, mod=12, var=13)
• reserve 26-31

Format

The above special characters are reffered as ^n (i.e. ^1 means separator 1). Brackets and ellipsis are not part of the code.

^1^2^3 (txgs header, most text editors destroys it if player tries to manually edit&save)
(game version)^1(game position node name)
[^9(node description)
  [^4(dir target)^2(dir description)]...
  [^4(move target)^2(move mod)]...
  [^5(resource name)]...
]...
[^10(item location)^1(item nominative)^1(item appendix)
  [^4(item events called count)]... (the order is as it goes in the txg source)
]...
[^11(action description)^1(action called count)]...
[^12(mod name)^1(mod called count)]...
[^13(var name)^1(var value)]...