109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# 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`.
|
|
|
|
## 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
|
|
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. ``.
|
|
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.
|