Embedding & Engine Guide

How to put JaiScript inside a C++ engine: the two-line quickstart, binding classes, choosing a backend, precompiled .jaibite bites, safety rails for untrusted script, static checking, hot reload, serialization, coroutine hosting, signals, the honest performance numbers, and the thread pool a host can run its own work on. All host snippets were compiled and run against the real library.

The embedding model is settled for 1.0; the exact C++ signatures may still change in a 0.x release. Stability has both lists.

A host moving to JaiScript from another library starts in the Code Migrations: Cereal and Boost.Serialization, Boost.Signals2, ChaiScript, sol2, Squirrel, pybind11 and Boost.Python, nlohmann::json, Qt properties and RTTR, and Lua or C++20 coroutines.

Embedding Quickstart
Six steps from nothing to a scripted, hot-reloading game loop: add JaiScript to a CMake, Visual Studio or Xcode build, run a script, bind a class, call a script function, reload an edit while the loop runs, and handle errors.
dynamic_binder: Binding C++ Classes
Bind a plain C++ class step by step, then declare a field once and it is reflected, script-visible and serialized; then the fluent binder chain underneath, verb by verb, and static binders for plain structs and templates.
Backends: Interpreter vs VM
One AST, two interchangeable backends held to byte-identical behavior; when each wins and how to A/B them.
jaibite: Parse Once, Ship Precompiled
Parse once, run many; the automatic .jaibite disk cache, and shipping precompiled scripts by hand.
Safety Rails
Host-controlled filesystem access and custom named permissions: default-on file access, default-off custom grants, and requirements that survive aliases and reflection. Configure budgets, memory caps, overflow and recursion limits, and understand why an engine is not a process sandbox.
Static Checking
Always strict: typed mistakes and undeclared names fail the load, before a statement runs. [[warn_mode]] relaxes one region, plus extern, casts, program-wide checking, and the precision map of what still fails at run time.
Hot Reload
The workflow at a glance, then the details: redefining a class migrates every live instance in place, the migration hooks, the host frame loop that reaches the imports, and code on the live stack.
Serialization
to_json/from_json in script, with a save-to-file recipe; a Cereal-shaped archive framework in C++; the binder chain doubles as the polymorphism declaration.
Coroutine Hosting
Coroutine handles from script and from C++: next, done, the frame-loop pattern and the native handle.
Signals & Observable Properties
Gameplay is event-shaped: firing and receiving signals from C++, the three routes a signal takes to become script-connectable (auto-bound, one binder line, or a named type), and observable values that announce their own changes.
Performance Notes
What the VM does for you (fused superinstructions, typed arrays, in-language parallelism), what idiomatic-fast code looks like and the rules that keep script code fast, the honest cost model, and real measured numbers: microbenchmarks vs Lua/Squirrel/ChaiScript and two whole games.
Debugging
Debug a script in VS Code step by step, or read a caught error's place and stack without a debugger. JaiScript ships a step-debugger core (breakpoints, pause, inspect/edit variables, step, resume) on both backends, a VS Code DAP attach, and a syntax-highlighting extension. It costs nothing until a session attaches.
Script-Extensible Objects: extend
A script class can derive a bound C++ class, and the script decides which object becomes which class: extend(object, Class) re-classes a host-owned object in place; every road back into script hands back the layer; hybrids serialize as themselves.
Editor Support: the Language Server
jaiscript_lsp answers the editor from the engine's own parser and strict checker: diagnostics as you type across a whole program (imported files at their own lines), go to definition, references, hover, completion, signature help and rename; the VS Code extension that launches it, and the host profile scripts are checked against.
Math Adapters: Host Vector Types
One JAI_BIND_* line makes your engine's own vector, point or color struct cross every binding as a script math value.
Thread Pool for Host Work
jai::thread_pool from one light header: shared and pinned queues, continuations that run on a worker or come back to the host's thread through run_posted, exceptions, spinning, and what destruction drops.
Host API in Depth
Functions and direct entries, live bindings to C++ variables and exactly what writes through them, running files, per-execution variables, calling script and reading state back, every error surface, the clock scripts read, and the worker count parallel regions use.
Building JaiScript into a Host
CMake, Visual Studio and MSBuild, Xcode and an installed package in full: the sources to add, one file or per file, the include path, standard, flags and defines, and Debug and Release notes.
jai_spider: a Web Application Host
A web app in JaiScript: jai_spider app.jai serves HTTP/1.1, hands each request to the handler the app gives spider::spin, routes with a script spider::Router, reaches other servers with spider::catch and spider::sling, stores in SQLite through bound parameters, keeps cookie sessions, serves static files, and reloads a saved module on the next request while a rejected edit keeps the old code serving.