Embedding & Engine Guide

How to put JaiScript inside a C++ program. Host snippets on these pages are compiled and run against the library.

Start here: the Quickstart (six steps to a scripted, hot-reloading loop), then Building JaiScript into a Host for your build system (or Visual Studio, Step by Step from a fresh Windows install) and Host API in Depth for the calls every host makes. The other chapters each cover one subsystem and can be read in any order.

The embedding model is settled for 1.0; exact C++ signatures may still change in a 0.x release (Stability). A host moving 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: add JaiScript to the build, run a script, bind a class, call a script function, reload an edit while the loop runs, handle errors.
dynamic_binder: Binding C++ Classes
Bind a plain class; declare a field once and it is reflected, script-visible and serialized; the binder chain verb by verb; static binders for structs and templates; atomics.
Backends: Interpreter vs VM
Two backends held to identical behavior, and how to compare them.
jaibite: Parse Once, Ship Precompiled
Parse once and run many times, the automatic .jaibite disk cache, and shipping precompiled scripts.
Safety Rails
What a script can reach by default, filesystem and custom permissions, execution budgets, memory caps and depth limits, and the recipe for untrusted script.
Static Checking
Typed mistakes and undeclared names fail the load before a statement runs; [[warn_mode]], extern, program-wide checking, and what still fails at run time.
Hot Reload
What a reload checks and applies, how live instances migrate when a class changes, the migration hooks, and the host loop that reaches the imports.
Serialization
to_json/from_json in script, the C++ archives, polymorphic pointers, and versioning.
Coroutine Hosting
Driving script coroutines from a frame loop, and the native handle.
Signals & Observable Properties
Firing and receiving signals from C++, the routes by which a signal becomes script-connectable, and values that announce their own changes.
Performance Notes
What the VM does for you, what keeps script code fast, the cost model, and measured numbers.
Debugging
Step through a script in VS Code, or read a caught error's place and stack without a debugger.
Script-Extensible Objects: extend
A script class derives a bound C++ class, and extend(object, Class) re-classes a host-owned object in place.
Editor Support: the Language Server
jaiscript_lsp: diagnostics, go to definition, references, hover, completion and rename from the engine's own parser and checker, and the VS Code extension that launches it.
Math Adapters: Host Vector Types
One JAI_BIND_* line makes your own vector, point or color struct cross every binding as a script math value.
Thread Pool for Host Work
jai::thread_pool: shared and pinned queues, continuations on a worker or back on the host's thread, exceptions, and destruction.
Host API in Depth
Functions, live bindings to C++ variables, running files, per-execution variables, calling script and reading state back, every error surface, the clock, and the parallel worker count.
Building JaiScript into a Host
CMake, Visual Studio, Xcode and an installed package: sources, include path, standard, flags and defines.
jai_spider: a Web Application Host
A web application in JaiScript: HTTP serving, routing, outbound requests, SQLite, sessions, static files, and reload on the next request.
Foundry: Testing a Host
The test framework JaiScript's own suite uses, for your project: a suite, the checks, the runner's arguments, and the test executable's build.
Visual Studio, Step by Step
From a fresh Windows install to a program that runs a script: the C++ workload, then a Console App project or a CMake folder, and the fix for each error a missed step gives.