#+title: Kroz language design
- tags :: [[file:20210429105507-my_programming_languages.org][my programming languages]]

Kroz is a programming language project I'm using to better familiarize myself
with [[file:20210307165050-racket.org][Racket]] and implementing languages in Racket.

Kroz is a language that's used for designing text-based adventure games. The
output of a Kroz program is a full-blown adventure game.

* Design
The language consists of a series of prompts and expected responses.
A Kroz game is a tree of decisions.

#+begin_example
; this is a comment
game_start:
    prompt "You find yourself in a dungeon cell with only a rope. What do you do?"
    actions:
        "climb rope" -> climb_rope_action
        "yell" -> end_game "A guard comes and kills you."

climb_rope_action:
    prompt:
    ---
    This is how you'd write a multi-line prompt.
    ---
    actions:
        "follow road" -> ...

begin_game game_start
#+end_example

** Scenes
Every program is broken into scenes. Each scene has an identifier specified with
it:

#+begin_example
game_start:
...
#+end_example

Scenes have a =prompt= and =action=.
** Prompt
The prompt is the text that is displayed at the beginning of a scene.
Prompts can be strings surrounded by quotes, such as:

#+begin_example
prompt: "You enter a cave."
#+end_example

or multi-line string literals surrounded by =---=. The first =---= must begin on
a new line.

#+begin_example
prompt:
---
This is a raw string.

This will be displayed to the user exactly as you type it!
---
#+end_example
** Actions
Actions are essentially key-value mappings from accepted inputs to other scenes,
delimited by new lines. Their basic syntax is:

#+begin_example
ACTION = WORD_LIST -> SCENE_NAME \n
WORD_LIST = WORD+
WORD = ".*"
#+end_example

For example:
#+begin_example
actions:
"follow road", "grab rope" -> next_scene_name
"cut rope"                 -> different_scene
#+end_example

Whitespace is ignored on a line-by-line basis.
** Special actions
There are two special reserved actions, =begin_game= and =end_game=.

*** =begin_game=
=begin_game= tells the program which scene kicks the game off. Conventionally it
should be placed at the end of a Kroz file.

#+begin_example
begin_game first_scene
#+end_example

*** =end_game=
=end_game= ends the game. It takes no argument and can be used in an action
list.

#+begin_example
actions:
"foo" -> end_game
#+end_example