← Back to Ryah’s lab

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.

Start with the control you need.

Flags Recognize a scene mode
Declare a condition such as battle_active. The router evaluates it from the scene each turn. A flag needs a hook to trigger custom behavior, and it does not remember past events.
Specs Shape a story
Supply the main arc, its beats, and optional parallel tracks. Start here if you want control over a mystery, romance, or quest’s structure. The engine still evaluates locks and carries progression forward.
Hooks Add your own mechanics
Route a condition to a custom instruction function. Use this for something the normal scene workflow does not cover, such as a minigame or a special combat mode.

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.

Illustrative card text · main arc spec
[[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.

Illustrative card text · flag and returning hook
[[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.

  1. Check the integration. Confirm the preset version, SDK regex conversion, and prompt slots match the public reference before relying on shorthand.
  2. Try one short arc. Give it a testable objective and specific beats. Add tracks or hooks when the scenario needs them.
  3. 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.
  4. 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