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:

git submodule update --init --recursive

Build (Windows / MSVC)

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)

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

Run tests

From the project root (after configuring the build):

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.

Filesystem / Writable Data

user/ is the only writable directory in runtime mode.
In editor mode (--editor), scene files in scenes/ and the asset registry at assets/registry.toml are writable.
Scene saves are blocked outside editor mode.
Logs are written to user/log.txt.

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 scripts/sync_wiki.sh

CI sync (automated):

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

To create the deploy key and CI secret:

# 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

Add or edit Markdown files under docs/.
Put images in docs/images/ and reference them with relative paths, e.g. ![Alt](images/diagram.png).
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 for the format and examples.