Covers Engine 2.0.0
DARTWIC Builder
Follow native builds, fixed-channel configuration, binding changes, and runtime activation.
DARTWIC Builder records the engine’s work to configure fixed channels, compile native DCode, bind channel references, and activate runtimes. Open DARTWIC Builder in the Interface sidebar when starting a project, activating a native script, or changing a plugin task’s configuration.
Builder is part of the engine. Its panel displays sessions and their detailed events; opening it does not compile a project. Native compilation starts when you activate a file configured for Native C++ or when that file is activated at engine startup. Native C++ Execution covers tool installation and a first build.
Read a build session
Expand the session for your script or task, then inspect its stages and event details:
| Stage | What to look for |
|---|---|
PLAN | Script, task, trigger, and selected backend. |
CHANNELS | Declared fixed outputs, channels promoted from dynamic storage, and missing reads created as dynamic. |
BIND | Each channel’s fixed/dynamic storage and input/output role; affected consumers rebound after a layout change. |
COMPILE | Generated C++, compiler errors, artifact path, duration, or CACHE_HIT. |
ACTIVATE | Replaced tasks, released/restored task groups, and previously running tasks restarted. |
VERIFY | READY after successful activation, or the failure that prevented it. |
Stages can appear in a different order or be absent when no compilation is needed. A fixed-channel warning can coexist with a successful activation: a dynamic read is allowed, but may be unintended for a control path. Expand the context to find the channel name.
The panel also shows allocated fixed slots and reserved capacity. Fixed channels ready means the layout is protected from direct changes; it does not prove every task is running or every input is fixed.
What happens during configuration
Native activation discovers direct channel outputs across configured native files, reconciles them with RAPID, and resolves the current file’s references. This allows a consumer to bind to a configured native producer even if the producer file has not yet been activated. Read-only missing channels are created as dynamic with an initial value of zero, accompanied by a warning.
Declared layout changes take an exclusive configuration boundary. New task transactions wait while active transactions finish, then the engine applies the change. You do not need to manually unlock fixed configuration to activate DCode or apply a task’s declared configuration.
When a task configuration or native producer changes storage, affected loaded native consumers can be rebound without recompiling their source. Builder records that impact. Ordinary value writes keep the existing storage class; they do not perform this configuration work.
Reload and startup
During a native rebuild, existing running tasks initially continue on their current artifact and new start requests wait. After the new artifact loads and resolves, activation replaces the affected runtimes and restores tasks that were running. This is a runtime replacement: native task state resets at start, so do not assume counters or controller state survive it unchanged.
A failed build does not automatically switch the file to Lua. Read the failed session and compare the editor’s selected backend and source with the loaded runtime. Do not infer that a requested edit is active just because an older task is still running. Channel reconciliation can happen before compilation fails, so a failed build is not a promise that every configuration side effect was rolled back.
At startup, Builder inventories plugin tasks with fixed channels and activates configured native startup scripts, then protects the fixed layout. A failed native startup script produces a failed startup session rather than a successful READY result. Startup channel overrides are applied after fixed declaration and before deferred runtimes start; see Startup values.
Resolve common problems
| Symptom | Next step |
|---|---|
| CMake configuration fails | Read the compiler log. Check tools in the engine process’s environment, especially Windows VS 2022 ClangCL or Linux Ninja. |
| C++ compilation fails | Use the reported .dcode line and native diagnostic. Validation catches many unsupported constructs, but compiler/type errors can still arise during activation. |
| Artifact cannot load | Inspect the load/ABI error and artifact path. A compiled file is not necessarily loadable on another machine. |
| Unexpected dynamic binding | Check the producer’s configuration and spelling. Declare the channel fixed in its owning plugin task or native producer; merely reading a name does not make it fixed. |
| Multiple direct writers warning | Give the output a clear owner or define task ordering deliberately. Fixed storage alone does not order independent tasks. |
| Fixed capacity exhausted | Increase rapid_fixed_channel_capacity in the engine configuration and restart. It defaults to 4096; capacity is allocated when RAPID is constructed. |
| Builder waits for transactions | Inspect the oldest active transaction’s owner and age. A long callback, native sleep, or blocking driver work can hold configuration up. Execution-line details are available where the runtime supplies them. |
| Build succeeds but nothing changes | Confirm the requested source/backend is loaded, start the task, and inspect authority, bindings, and task timing. |
Inspect Builder through TEMPEST
Send these operations through a registered TEMPEST connection:
| Operation | Payload | Result |
|---|---|---|
dartwic/builder/get-report | {"script_path":"native_demo.dcode","limit":100} | Matching sessions/events plus fixed configuration, loaded scripts, and active transactions. Omit the filter for the whole project. |
dartwic/get-script-build-report | {"filePath":"native_demo.dcode"} | Latest compiler report and artifact/log paths for that file. |
rapid/get-fixed-configuration | {} | sealed, state, automatic_updates, fixed slot count, and capacity. |
Script, task, and channel filters match each record’s own context. They can omit events whose context only names affected consumers. To retrieve a whole session, take its id from sessions and make a second request with only {"session_id":"<returned id>","limit":300}. Do not keep the script filter on that second request.
The generated operation reference documents request and response fields. Use the compiler report for build output and Builder’s final activation event for runtime readiness.