# 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 that's in the /stories/ directory.

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

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.

## Implemented stuff

### Commands

| Command         | Implemented |
| --------------- | ----------- |
| END             | Yes         |
| CHOICE/OR/OR    | Yes         |
| IF/ELSE IF/ELSE | No          |
| GOTO            | Yes         |
| 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          |
| INPUT      | Partially   |

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