131 lines
5.3 KiB
Markdown
131 lines
5.3 KiB
Markdown
## Simian
|
|
|
|
Simian is a small Raylib + AngelScript test project, refactored to be easy to extend and to show a safe hot-reload workflow for AngelScript.
|
|
|
|
This README was updated to reflect the current layout, build paths, and the small CMake wrapper approach used to optionally build ImGui / rlImGui when those folders are present.
|
|
|
|
## What changed
|
|
|
|
- The original single-file demo was split into modules: Application, ScriptEngine, ScriptBindings and HotReload.
|
|
- Hot-reloads are performed safely: scripts compile into a temporary module first and only replace the running module on successful compilation. Compilation errors will no longer crash the running app.
|
|
- CMake wrappers live in `cmake/` to build third-party projects that don't ship a CMakeLists.txt (example: ImGui, rlImGui). This keeps submodules untouched.
|
|
- A `Justfile` was added with convenient recipes for configure, build, run and cleaning.
|
|
|
|
## Quick start (Windows)
|
|
|
|
Open a developer prompt for Visual Studio or use PowerShell / cmd configured for MSVC.
|
|
|
|
Clone with submodules:
|
|
|
|
```powershell
|
|
git clone --recurse-submodules <repo-url>
|
|
cd Simian
|
|
```
|
|
|
|
Using the included `Justfile` (optional):
|
|
|
|
```powershell
|
|
# from project root
|
|
just configure # runs cmake -S . -B build -G "Visual Studio 17 2022" -A x64
|
|
just build # builds Debug by default (uses cmake --build)
|
|
just run # runs the built executable (Debug)
|
|
```
|
|
|
|
Or use raw CMake commands:
|
|
|
|
```powershell
|
|
mkdir build; cd build
|
|
cmake -G "Visual Studio 17 2022" -A x64 ..
|
|
cmake --build . --config Release
|
|
# run:
|
|
build\Release\simian.exe
|
|
```
|
|
|
|
If you are using cmd.exe, the same commands apply (adjust quotes for generator if needed).
|
|
|
|
## Linux / Unix
|
|
|
|
```bash
|
|
git clone --recurse-submodules <repo-url>
|
|
cd Simian
|
|
mkdir build && cd build
|
|
cmake -G "Unix Makefiles" ..
|
|
cmake --build .
|
|
./simian
|
|
```
|
|
|
|
## Project layout (important files)
|
|
|
|
```
|
|
Simian/
|
|
├─ CMakeLists.txt # top level CMake
|
|
├─ Justfile # convenience tasks (configure/build/run/clean)
|
|
├─ include/ # public headers (Application, ScriptEngine, ScriptBindings, HotReload)
|
|
├─ src/ # implementation
|
|
├─ scripts/ # AngelScript source files loaded at runtime
|
|
├─ external/ # git submodules (raylib, angelscript, optional imgui/rlImGui)
|
|
└─ cmake/ # local CMake wrappers (imgui, rlImGui)
|
|
```
|
|
|
|
## Hot-reload notes
|
|
|
|
- The app watches `scripts/` for changes. When a script is updated it is compiled into a temporary AngelScript module.
|
|
- If compilation succeeds, the temp module replaces the live `main` module and new functions are used. If compilation fails, the running module is left intact and a single-line error is shown on-screen.
|
|
- This avoids crashes that happen when a script with compilation errors would otherwise replace/break function pointers while the engine is executing.
|
|
|
|
## ImGui / rlImGui (optional)
|
|
|
|
The repository prefers to keep upstream code as submodules. Some upstream projects (like certain ImGui tags or rlImGui) don't provide a CMakeLists.txt. To support those without editing submodules, the project includes small wrappers in `cmake/`:
|
|
|
|
- `cmake/imgui/` builds ImGui core (and optionally backends) when `external/imgui` is present.
|
|
- `cmake/rlImGui/` builds the rlImGui integration and links it to the `imgui` target if available.
|
|
|
|
If you prefer to use the upstream CMake (when present), the top-level `CMakeLists.txt` will prefer `external/rlImGui`'s CMake if it detects one; otherwise it falls back to the wrapper.
|
|
|
|
To add ImGui/rlImGui as submodules:
|
|
|
|
```powershell
|
|
# from repo root
|
|
git submodule add https://github.com/ocornut/imgui.git external/imgui
|
|
git submodule add https://github.com/NeoSpark314/rlImGui.git external/rlImGui
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Then re-run CMake from a clean build directory.
|
|
|
|
Troubleshooting: if Git warns about "embedded git repository" when adding files, convert the folder to a submodule (remove cached tracked files, then add as submodule) — this README intentionally avoids modifying submodule contents.
|
|
|
|
## Tests / Verification
|
|
|
|
Quick smoke test after building:
|
|
|
|
```powershell
|
|
# run the Debug build
|
|
build\Debug\simian.exe
|
|
```
|
|
|
|
You should see the Raylib window. The running console prints from script when the default script executes (e.g. "[Script] Hello from AngelScript!").
|
|
|
|
If a script has a compilation error, the app will continue running and a brief error message is presented on the top-left of the window.
|
|
|
|
## Updating submodules
|
|
|
|
Keep submodules pinned for reproducible builds. To update them safely:
|
|
|
|
```powershell
|
|
cd external/raylib && git fetch && git checkout <commit-or-branch>
|
|
cd ../angelscript && git fetch && git checkout <commit-or-branch>
|
|
cd ../.. && git add external/raylib external/angelscript && git commit -m "Update submodules"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- The project was developed and tested on Windows with Visual Studio; Linux builds are supported but may need X11 / audio dev packages installed depending on your environment.
|
|
- The codebase avoids changing tracked submodule contents; use the `cmake/` wrappers when a submodule doesn't include a CMake build.
|
|
|
|
## License
|
|
|
|
* Raylib: Zlib License (see https://github.com/raysan5/raylib#license)
|
|
* AngelScript: MIT License (see https://github.com/angelcode/angelscript/blob/master/license.txt)
|
|
* Simian: Not open source (yet)
|