AetherKit SDK / Author’s guide
Your story.
Inside the simulation.
Give your character card its own story beats, pacing, and mechanics. AetherKit connects the scenario you write to the world Vexa runs.
A card can carry a whole scenario.
Vexa supplies the simulation: characters, relationships, off-screen activity, and story progression. AetherKit gives card authors places to supply their own structure within it. You can decide what a mystery builds toward, when a reveal becomes eligible, or how a custom sanity mechanic behaves.
The SDK is a prompt-authoring interface. Its declarations become inputs to Antithesis, Vexa’s experimental dynamic chain of thought (CoT), through the accompanying regex and variable setup. The model interprets those instructions during play; they are not compiled application code.
Antithesis distributes callable <fn:x> blocks
throughout the prompt. At its router, the current scene setup
determines which route to follow and which procedures to call.
AetherKit injections join that flow: flags describe conditions,
hooks connect them to custom functions, and those functions return
to the caller. Hooks work within the preset's routing rules; they
do not create arbitrary page jumps.
A small mystery, with room to go wrong.
Start with an objective that can succeed or fail. Then write concrete events across four acts: Ki introduces, Shō develops, Ten reframes, and Ketsu resolves. This compact example gives each act one beat.
[[spec: arc]]
name: The Missing Signal
objective: identify the source of the signal
genre: mystery
focus: {{user}}
role: focus
duration: 2 days
ki (1):
Mara brings a damaged receiver [C:Mara]
sho (1):
The receiver plays a distress call [D:ki1]
ten (1):
Mara identifies her own voice in the call [C:Mara] [D:sho1]
ketsu (1):
Mara opens the transmitter log [C:Mara] [D:ten1]
[[/spec: arc]]
Write Mara and the receiver into your scenario. The log is a chance to identify the source; the objective’s outcome still depends on what happens in play. Leave space for refusal, a missed clue, or a failed attempt.
objective- Defines what must resolve. Elapsed time alone does not advance the arc.
duration- Sets pressure. When the time runs out, the threat can escalate off-screen while the objective remains unresolved.
[C:Mara]- Requires Mara to be present. A character lock keeps a reveal tied to the person who can deliver it.
[D:ki1]- Requires the first Ki beat to have fired. Dependencies hold later events until their prerequisites happen.
The documented pacing rule allows at most one main-arc beat per turn. An unlocked beat is eligible; it still needs an opening in the scene.
More ways to hold a reveal
Use [T:turn 3] for an earliest turn,
[R] for a private scene with the involved parties
present, and [K:user_has_key] for a custom
prerequisite. Future beats are spoilers: keep their content out
of reader-facing prose. The reference explains the engine’s
spoiler encoding and complete lock syntax.
Let other stories keep moving.
A main arc gives the scenario a spine. Parallel tracks let an NPC’s investigation, a rival’s plan, or a side quest unfold alongside it. They can advance while the player character is elsewhere.
A track spec needs an objective, an in-world trigger, an ordered chain of steps, and routes for completion and failure. A failed track leaves a lasting consequence. If several tracks orbit one central secret, reserve its resolution for the designated final track.
For the signal mystery, a repair-shop inquiry could uncover a serial number while a rival searches for the transmitter. If the inquiry fails, the rival might gain the evidence first. Both outcomes give the world somewhere to go.
Track fields and full example ↗When a story needs a new rule.
Combine a flag with a hook to route a scene to your own function. This example adds an instruction before normal scene processing continues.
[[flag1: signal_audible]]
[[hook1]]
condition: signal_audible = TRUE
call: missing_signal_listen
[[/hook1]]
<fn:missing_signal_listen>
Describe the signal through sounds {{user}} can hear.
Keep the source unrevealed until discovered in-scene.
⇤
</fn:missing_signal_listen>
⇤ returns to the caller so normal routing can
continue. A hook that uses
⇥ <page:output> replaces the scene workflow and
skips its usual tail checks. That advanced path must handle its
own exit, perception limits, and character fidelity.
Use state for memory, dice for uncertainty.
A flag answers “is this happening now?” A
[[state]] block carries custom values between turns,
such as receiver damage, a score, or clues found. Custom
[[dice1]] through [[dice5]] blocks
supply named frontend rolls for your functions to read. Your
instructions must explain how those rolls change the state.
Flags and hooks also have five numbered slots each. Choose distinctive function and die names, and leave the core emotion, persistence, world simulation, and arc lifecycle functions intact.
Make one small thing work first.
- Check the integration. Confirm the preset version, SDK regex conversion, and prompt slots match the public reference before relying on shorthand.
- Try one short arc. Give it a testable objective and specific beats. Add tracks or hooks when the scenario needs them.
- Play through success and failure. Test a missing NPC, an unmet lock, and an unsuccessful choice. Check that the story still has a next step.
- Inspect the internal states block. The ARC ENGINE section shows LOCKED, UNLOCKED, and FIRED beats; QUESTS shows track status. Check these when prose alone leaves progression unclear.
A beat or hook did not fire. What should I check?
For a beat, inspect its character, time, and dependency locks, then check whether another main beat already fired this turn. For a hook, check that its flag derives true and its function name matches the call. If the shorthand never reaches the preset, inspect the regex and variable setup before changing the story.
Keep the reference nearby.
For exact syntax, reserved names, state and dice examples, and the full integration contract, continue to the public SDK document.
Open the SDK reference ↗Explore Vexa’s philosophy