happening/README.md

Happening

An interactive story telling software. Read and write people's stories

Install

This is not really out of development, but to run it, clone the repo, go into /server/ and use cargo run story.zip to run a file called story.zip that's in the /stories/ directory.

Technical Details

Back-end server -- Rust

The server component of Happening will be written in Rust.
Parses the code and sends it via the API.
File layout:

• animations/
• features/
• scenes/
• images/
• stories/
  • file.zip
    • main.ha
    • other.ha
    • characters.json
    • about.json
    • animations/
    • features/
    • scenes/
    • images/

The variables are stored as a hashmap, characters are objects.

API

Using the network interface, port 20264.

Characters are sent to the frontend and stored there when the character is created on the frontend.

{

request_type: String,

content: String,

character: String,

}

Frontend -- Python

Things the frontend can do:

• Output text
• Display the character
• Move characters around
• Display a choice to the user that gets sent back to the server

Syntax

Setup

This is done in the about.json file,

{

"title": "My Great Story",

"description": "please read!"

}

Characters

See Character documentation for more info Referencing a character using the @, @NARRATOR is reserved for the Narrator.
Customisation is done with @CHARACTER change <feature> into <feature name>
Move a character with @CHARACTER to fr

Note

fr means front-right for instance.

Outputs

@CHARACTER says "this string
is multi-line
and ends with a"

Variables

Variables are referenced with the $, only integers will be supported.

Selection

Condition based:

if (condition) {

}

elif (condition) {

}

else

}

Choice based:

choice "choice 1" {

}

or "choice 2" {

}

or "choice 3" {

}

Positioning

@CHARACTER to position

PAN to position

Other

label:

GOTO label

Ending

END to exit out of the story

Implemented stuff

Commands

Command	Implemented
END	Yes
CHOICE/OR/OR	Yes
IF/ELSE IF/ELSE	No
GOTO	No
PAN	No

Character sub-commands

Character Command	Implemented
SAYS	Yes
CHANGE	Yes
TO	Yes
ANIMATE	Yes

Other Features

Feature	Implemented
Variables	No
about.json	No

Error codes

Code ID	Meaning	Possible remedies
0	Success	N/A
1	File unexpectedly reached termination point	Make sure there is an END statement in the code.
2	Data to send Mutex was poisoned
3	Characters Mutex was poisoned
4
5
6
7
8
9
10	No filename specified for	When running the server, pass the name of the story zipfile as an argument.
11	Failed to open file	Make sure the story zipfile exists and is accessible to the server.
12	Failed to open archive	Make sure the story file is a zip archive.
13	Unable to setup the characters hashmap.	Make sure the characters.json file exists, is valid JSON and contains valid characters.
14	Unable to read the main story file.	Make sure the story.ha file exists and is readable.
15	Unable to tokenise data	Make sure your code is correctly formatted