# Usage

This page documents how to build, run and maintain the Simian project and how to publish documentation to the Gitea wiki.

## Prerequisites

- Git
- CMake (>= 3.16; 3.25 recommended)
- A C++ toolchain (Visual Studio on Windows, GCC/Clang on Linux/macOS)
- Optional: SSH access to your Gitea instance (for wiki sync)

If you just cloned the repository, initialise submodules:

```bash
git submodule update --init --recursive
```

## Build (Windows / MSVC)

```powershell
mkdir build
cd build
cmake -S .. -B . -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release
# Run
.\Release\simian.exe
```

## Build (Linux / macOS)

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
./simian
```

## Run tests

From the project root (after configuring the build):

```bash
cmake --build build --config Release --target RUN_TESTS
# or use CTest
ctest --test-dir build --output-on-failure
```

## Scripting / Hot-reload

- Scripts live in the `scripts/` directory (e.g. `scripts/game.as`).
- The engine watches the scripts directory and will hot-reload scripts when changed.
- Predefined API is declared in `scripts/as.predefined`.

## Documentation & Wiki

Docs source lives in the `docs/` folder. The repository contains a CI workflow and a local script to mirror `docs/` to the Gitea wiki.

Manual sync (local):

```bash
bash scripts/sync_wiki.sh
```

CI sync (automated):

1. The workflow `.gitea/workflows/sync-docs-to-wiki.yml` runs on pushes that affect `docs/**`.
2. The workflow requires an SSH private key in repository secrets named `WIKI_SSH_KEY`.

To create the deploy key and CI secret:

```bash
# Generate a keypair (do not commit the private key)
ssh-keygen -t ed25519 -C "simian-wiki-ci" -f simian_wiki_ci -N ""

# Add simian_wiki_ci.pub as a deploy key in your Gitea repo: Settings → Deploy Keys
# Enable write/push access for that key.

# Copy the private key (simian_wiki_ci) into your CI provider as secret WIKI_SSH_KEY.
```

Notes:
- The workflow clones the wiki remote `git@gitea.appstack.me:nick/simian.wiki.git` and pushes updates.
- If your Gitea host/paths differ, update `.github/workflows/sync-docs-to-wiki.yml` or the `scripts/sync_wiki.sh` script accordingly.

## Adding / Updating Documentation

1. Add or edit Markdown files under `docs/`.
2. Put images in `docs/images/` and reference them with relative paths, e.g. `![Alt](images/diagram.png)`.
3. Commit and push to the repo; CI will sync changes automatically (once secrets/deploy-key are configured).

## Troubleshooting

- If the CI job fails with authentication errors, confirm the deploy key was added to the Gitea repo and the private key is stored in the CI secrets as `WIKI_SSH_KEY`.
- To debug locally, run the `scripts/sync_wiki.sh` script and watch for `git push` errors.

## Scenes

Scenes are stored as TOML files in `scenes/`. Use `Scene::Load("scenes/demo.toml")` from scripts to create entities with hierarchy relationships.
See [Scenegraph](Scenegraph.md) for the format and examples.