# Happening

An interactive story telling software.
Read and write people's stories
For help with making a story, see [this documentation](/docs/MAKING_A_STORY.md)
For help with syntax, see [this documentation](/docs/SYNTAX.md)

## 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, relative to your current location.

## Technical Details

### File layout

- animations/
- features/
- scenes/
- images/
- stories/
  - file.zip
    - main.ha
    - other.ha
    - characters.json
    - about.json
    - animations/
    - features/
    - scenes/
    - images/
      
### Back-end server -- Rust

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

The variables are stored as a hashmap, characters are structs in a hashmap.<br/>

### API

Using the network interface, port 20264.<br/>
> [!NOTE]
> The port is configurable in config.json of the server, client should be flexible with ports.

Characters are sent to the frontend and stored there when the character is created on the frontend.<br/>
There are 4 endpoints.

#### /happening

GET Returns what is happening on the next cycle:

```
{

request_type: String,

content: String,

character: String,

choice: [String,String,String,...]

}
```
#### /character/\<character name\>
GET Returns the struct of the character, ideally this should only be gotten when a new character is made or a character changes a feature.

#### /choice
POST the choice as a JSON formatting number, eg 1 to choose choice index 1, returns "ack" as acknowledgment.

#### /input
POST not yet fully implemented on the syntax side but allows client to send a user input to the server as text. returns "ack" as acknowlegment.

### Frontend -- Python

Things the frontend should be able to:

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

### Files

For more info on these files see [Making a Story](/docs/MAKING_A_STORY.md)

#### story.ha

This contains the code for the story, syntax for writing the code can be seen in [the syntax section](/docs/SYNTAX.md)

#### about.json

This file contains details about your story such as the title and description.

#### characters.json

See [Character documentation](/docs/CHARACTER.md) for more info
Referencing a character using the @, @NARRATOR is reserved for the Narrator.<br/>
Customisation is done with @CHARACTER change \<feature\> into \<feature name\><br/>
Move a character with @CHARACTER to fr

> [!NOTE]
> fr means front-right for instance.

## TODO
- Variables
- /about.json
- If/Else if/Else
- PAN
- INPUT
- tokeniser check for lack of END
- Fix no closing brace edge case
- Support single quotes for strings
- Brace index getter check for closing
- Proper Error messages centralised???

## 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                                              |