EDGEDIR / DOCS

Design

Draft 1, agreed by the owner on 2026-11-16, with the answers in “Questions and the owner’s answers”. Each phase still gets its own plan, agreed before it is built. Nothing here is built. Facts about the other tools were read from their repos on 2026-11-16; each table says where. Anything marked unverified has not been checked in the game or in code.

What the owner asked for

From the owner, 2026-11-16:

# Ask
O1 A director’s tool for animated sequences and scenes in the game
O2 Choose an NPC model, put an animation clip on a timeline for it, then a second clip
O3 A transition clip between two animation clips, made by an AI provider or by EDGEdir’s own logic, so the two view as one
O4 The timeline looks and behaves like EDGEwave’s
O5 Many tracks: an NPC with its animation clips, audio, camera positions at set times, a REDnode script or mod tool, a 2D video
O5a Added the same day: a weather track, and an AI track. What the AI track does is not decided; it might call REDagent in the game for a response
O6 The Desk and Library of the other tools: scenes are made and edited on the Desk, then go into a project or the Library
O7 Scenes are packed for the game. This probably needs new REDnode features
O8 A preview of the scene inside EDGEdir

What exists today

The game and REDnode

Source: REDnode 0.66.8, docs/world.md and packages/rednode/src.

Fact Consequence for EDGEdir
Only a workspot plays an animation on a spawned person. No base-game call plays an animation by name (unverified for Codeware) Every actor’s clips must sit in a workspot the actor carries
world.spawn({ record, workspot }), world.useWorkspot(id, { entry }), stopWorkspot, workspotState exist. entry jumps to a named animation in the workspot The calls a player needs are mostly there. Their in-game test (A2) has not run yet
The game’s own workspots do not fit: gameplay ones loop and walk in, quest ones play once after a T pose EDGEdir must write its own .workspot per actor. Writing one with REDbridge’s cr2w calls is unverified. REDnode’s notes propose the same route and call it a second spike
A REDnode package has no per-frame tick and no game-time timer. It has setTimeout on the real clock. Each game call answers a frame or two later A scheduler in a package is good to about 1 to 3 frames, and drifts when the game pauses or slows time. A frame-true player needs a new REDnode feature
world.move teleports a spawned thing and is cheap enough to call each frame. No walking to a point, no look-at, no facial animation, no lipsync Actors move by their clips’ root motion or by a teleport. Faces are out of scope at first
No camera API. The known pattern: spawn an entity with a gameCameraComponent, activate it, move it with world.move, hand back to the first-person camera after. SetFOV eases over about 1 s Camera cuts are possible today. Smooth camera moves need the tick
audio.play(file, { delay, volume, ... }) and audio.event(name) exist. Sound at a place or on an entity is not scheduled Audio clips play flat (not placed in the world) at first
No video API. An overlay page could play <video> (unverified) The video track waits for a spike
The editor channel (%LOCALAPPDATA%\REDnode\editor.json, 127.0.0.1 only, a new bearer token each run, any Origin refused) has sound, TweakDB and give routes. No world or scene routes Playing a scene from VS Code needs new routes, or goes through a package
The game’s weather system is reachable through api while V is in the world; reading the rain state passed a REDnode test. Found by REDnode’s session on 2026-11-16 (REDnode #46): nothing in game 2.5’s script API sets the weather; the weather interface only reads. The owner (same day): it can be controlled, because the game’s photo mode changes the weather; it may need internal wiring and a new REDnode call. REDnode checked further: 2.5 has no set-weather function in its script types or as a name in the game’s program, so the old Cyber Engine Tweaks call does not work. The game’s own route is a quest node that sets a weather by its TweakDB id (Weather.*), with a blend time and a priority, and can reset it. REDnode plans a plugin call from the function that node uses (world.setWeather, world.resetWeather), as a small spike after the workspot run The weather track stays in the plan. Its in-game half waits on a REDnode call (set a named state with a blend time, read the state, give it back, list the states), asked for on REDnode #46
REDagent 0.4.4 has an agent API for mods: a mod asks a question and gets a plain-text answer (agent.ask). An answer takes seconds, costs the player money, and needs the player’s own key An AI cue cannot be frame-timed, and its result differs each run
world.load reads EDGEbuilder’s <name>.scene.json (meshes, entities, NPCs standing idle) An EDGEbuilder scene can be the set an EDGEdir scene plays on

Game files: REDbridge and REDcode

Source: REDbridge 0.13.0 BridgeApi.Modkit.cs, its issue #14, REDcode docs/api.md and docs/design/animation.md.

Fact Consequence
project.export writes an entity in one appearance to one GLB on one joined skeleton, and an .anims file to glTF with one animation per clip, 30 fps, root motion on the Root node The preview can show the real character playing the real clips
The entity export leaves out the entity’s anim sets. An .anims GLB can be large (233 MB for the largest) The preview loads clips apart from the body and joins them by bone name. Exporting one clip from a set would need a REDbridge request (unverified whether the export can filter)
Animation names and frame counts can be read from an .anims today with cr2w calls. anims.info does not exist yet The Animations view can be built now, slowly; anims.info makes it fast
.anims import does not exist (#14). WolvenKit has the code; REDbridge does not call it New animation frames cannot reach the game yet. A transition made of new frames waits for #14
cr2w.fromJson, createInstance, patch, save write new files. EDGEquest writes .scene files this way and they play in the game Writing a .workspot the same way is likely. A .scene export is possible later
REDbridge speaks over stdio to the process that started it: no port. Other extensions reach it through REDcodeApi.bridge() EDGEdir depends on the REDcode extension, as EDGEwave does
REDcode has a three.js viewer that plays one character’s clips (A1, A2 built). Its mount point is not a contract EDGEdir builds its own viewport for many actors, with the same library

The other EDGE tools

Tool Fact Consequence
EDGEwave The timeline is a custom text editor over a JSON file (.edgewave), drawn on canvas, no framework. Each change posts the whole document back, so VS Code’s undo, redo and save cover it. One clip per track, no snap, no zoom in the lanes EDGEdir copies the pattern and the look, and adds what a scene needs: many clips per track, edge trim, snap, zoom. Code is copied, never imported (the platform’s rule)
EDGEwave Its API gives a sound event’s length and plays a sound now. It gives no waveform and no mix length An audio clip shows as a plain block until EDGEwave gives peaks (a request)
EDGEbuilder The shared Library’s rules: one root named in %APPDATA%\EDGE\library.json; an item is <name>.<kind>.asset/ with asset.json; a Desk is one tool’s own EDGEdir follows them as they are
EDGEbuilder Lists NPCs from TweakDB Character records, with appearances from the record’s .ent EDGEdir’s actor picker does the same
EDGEquest Writes .scene files. The game’s .scene is its own many-track timeline, but nothing starts a quest phase from outside a quest A native .scene export is a later route, built with EDGEquest
EDGEfab Its plan (not built) holds an animation index and clip tools: trim, loop, mirror, blend two clips, keyframes, text to motion Overlap. See the questions for the owner
EDGEfab, EDGEwave AI keys live in VS Code’s secret store, one per service, set by a command The same for EDGEdir

The idea

A scene is one JSON file with a timeline. Tracks hold clips. EDGEdir shows it three ways:

Way What it is Needs
Preview A 3D viewport in the editor: the cast’s real bodies playing the real clips, with transitions, camera and sound REDcode and REDbridge. No game running
Play The scene plays in the running game, where V stands or at a fixed place REDnode, and the scene’s packed files swapped in
Pack The scene goes into a project as files a player installs REDcode, REDnode on the player’s PC

Words, to keep them apart from the neighbours’ words:

Word Meaning
Scene EDGEdir’s timeline document: the direction, what the people and things do over time. Not the game’s .scene file, and not EDGEbuilder’s .scene.json
Set An EDGEbuilder scene: the stage, what exists in the world (props, people, vehicles), that an EDGEdir scene plays on. Optional. See Sets
Actor A character on an actor track
Mark Where an actor stands at the start, relative to the scene’s anchor
Anchor The scene’s origin in the world: in front of V, or fixed coordinates
Cue One timed order to the game, made from a clip when the scene is packed

The scene document

One file, <name>.edgedir, JSON, opened by EDGEdir’s custom editor and readable as text. Times are seconds, as in EDGEwave. Clip edges snap to frames of 1/30 s. No game data is stored in it: clips name the game’s files.

{
  "edgedir": 1,
  "name": "Alley talk",
  "fps": 30,
  "anchor": { "mode": "player", "distance": 3 },
  "set": null,
  "tracks": [
    {
      "id": "t1", "kind": "actor", "name": "Fixer",
      "actor": { "record": "Character.<record>", "appearance": "<appearance>" },
      "mark": { "position": [0, 0, 0], "yaw": 180 },
      "clips": [
        { "id": "c1", "kind": "anim", "start": 0, "in": 0, "out": 3.2,
          "anim": { "set": "<path>.anims", "name": "<animation name>" } },
        { "id": "c2", "kind": "transition", "start": 3.0, "length": 0.4,
          "method": "blend", "ease": "smooth" },
        { "id": "c3", "kind": "anim", "start": 3.2, "in": 0.5, "out": 6.0,
          "anim": { "set": "<path>.anims", "name": "<animation name>" } }
      ]
    },
    { "id": "t2", "kind": "audio",  "clips": [ { "id": "c4", "start": 1.0, "sound": { "kind": "event", "name": "<event>" } } ] },
    { "id": "t3", "kind": "camera", "clips": [ { "id": "c5", "start": 0, "length": 3.2, "position": [2, -1, 1.6], "lookAt": "t1", "fov": 35 } ] }
  ]
}

Track kinds

Kind A clip is Plays in the preview Plays in the game Phase
Actor An animation from a game .anims, with trim (in, out), speed and loop count; or a transition Yes A cue that jumps the actor’s workspot to the clip D2 on
Audio A game sound event, a WAV or OGG file, or an EDGEwave mix’s render Files yes; game events through EDGEwave (unverified) audio.event or audio.play D6
Camera A shot: position, aim (angles or look at an actor), FOV, for a length of time. A cut at first; a move between two shots later Yes, as the viewport’s camera A spawned camera entity D6
Script A call into a REDnode package at a time: a function name and JSON arguments Shown as a marker only Run by the player D8
Video A 2D video file shown over the game for a time In a corner of the viewport Unverified: an overlay page D8
Weather A weather state from the game’s list (a Weather.* TweakDB record), with a blend time, held for the clip’s length. One weather track per scene A tint and a label only; no rain or fog in the viewport A cue that sets the weather, and one that gives it back at the end. It needs a new REDnode call (REDnode #46) D6, or when the call lands
AI Not designed yet. A placeholder kind, so documents and the editor allow for it A marker Not decided After Q7

The AI track’s purpose is open (Q7). What is known limits it: a call to REDagent answers after seconds, not frames, and never the same way twice. So an AI clip is best seen as a window of time the answer may land in, with a rule for what the scene does meanwhile (hold, loop the actors’ clips, or go on). Some things it could do, for the owner to choose from:

Idea What the clip holds Needs
A line made in the moment A prompt; the answer is shown as a subtitle, or spoken through EDGEwave’s voices REDagent’s agent.ask; a voice route for speech
A choice of what plays next A prompt and named branches; the answer picks one Branches in the scene document, which the timeline does not have
A reaction to the player A prompt that reads the game’s state (where V is, what V did) and sets a script cue’s arguments The script track (D8)

The first is the smallest and fits a straight timeline.

One actor per actor track. Two actors that must move together (a handshake) are two tracks with clips at the same time. The game’s synced animation sets are not handled at first.

Animations and actors

The owner’s rule (2026-11-16): animations and actors are separate things while a scene is made. An animation is stored by itself. An actor is a character. Putting an animation on an actor’s track assigns it: that character acts it out at that time. The two are bound into game files only when the scene is packed.

Thing What it is Owned by Where it lives
Animation One clip of movement on a named rig. It knows no character The game, or EDGEfab for made ones (imported from a file, or made from video by an AI service) The game’s .anims files; EDGEfab’s items in the EDGE Library and in the open REDcode project
Actor A character: a TweakDB record and an appearance, and through its body a rig. V, the player, is one of them (the owner, 2026-11-16), in one body per scene; see D2 The game, picked in EDGEdir Named in the scene document
Assignment A clip on an actor track: this animation, on this actor, from this time EDGEdir The scene document
Binding The actor’s .workspot and anim sets, holding every animation the track uses EDGEdir at pack time The packed scene

The flow between the tools (the owner’s, with this section’s additions agreed on 2026-11-16):

Step Tool What happens
1 EDGEfab An animation is imported from a file or made from a video, tried on a character model, and stored by itself with Add to Library, or put into the open REDcode project with Add to Project
2 EDGEdir The animation shows in the Animations view, beside the game’s own: under Library, or under Project while that project is open
3 EDGEdir It is dragged onto an actor’s lane. It becomes a clip at that time, and the actor acts it out in the preview
4 EDGEdir Pack or Play in game binds each actor to its animations and writes the game files

What makes this work is the rig. An animation is made for one skeleton (the game has a few: the man’s, the woman’s, the big man’s and others), and an actor has one. So:

A clip names its animation one of two ways:

Source In the document Found by
The game "anim": { "set": "<path>.anims", "name": "<animation name>" } The index of the game’s files
A made animation, in the Library or the open project "anim": { "id": "<the item's id>", "name": "<its name>" } The item’s id, which never changes, so moving or renaming the item breaks nothing. EDGEdir looks in the open project first, then in the Library

The owner’s addition (2026-11-16): EDGEdir also sees the animations in the open REDcode project. A modder may use EDGEfab’s Add to Project and never touch the Library; with the scene editor open, the animation is dragged from the project onto a lane.

Point Agreed 2026-11-16
One way to name both The id. A Library item has one in asset.json; its copy in a project keeps it in the came-from note. An animation made straight into a project needs an id too (part of the request to EDGEfab)
Project before Library When both hold the same id, the project’s copy is used: it is the one that will be packed, and it may have been changed
Where in the project EDGEfab’s choice (source/raw is likely). EDGEdir finds animations by their note, not by a fixed folder
A Desk scene using a project animation Allowed, with a mark on the clip: the scene works only while that project is open. Move to Project clears the mark; Add to Library asks to add the animation too
Dragging From EDGEdir’s Animations view onto a lane. Dragging from REDcode’s project tree or the Explorer into the editor is unverified in VS Code (D2 checks it); an Add to Track command on the file is the fallback

A scene never holds a copy of an animation while it is on the Desk. When a scene goes into a project, the Library animations it uses that the project lacks are copied in with a came-from note, by the Library’s rules, so the project packs without the Library.

Two limits to say plainly:

EDGEfab’s answer (EDGEfab #7, 2026-11-16; its plan’s “Animations: the split with EDGEdir”), which EDGEdir accepted as it is:

Point EDGEfab’s shape
Kind anim: <name>.anim.asset, one clip per item. A group (a sit’s start, loop and end) is several items in one folder
In a project source/raw/<mod>/anims/<name>/<name>.glb, beside its record <name>.edgefab.json (kind: "anim", id). The record is the note EDGEdir finds it by
The id asset.json’s id, kept in the Library item, in source/library.json after a Library copy, and in the record
The facts An anim object in asset.json and in the record: rig (game path), seconds, fps, rootMotion, loop, name
The game’s format Once REDbridge #14 imports: source/archive/<mod>/anims/<name>/<name>.anims
Rig The man’s or the woman’s base rig, as the modder picks when trying it on a character. A service’s own skeleton is retargeted on import; the other rigs come after
When With EDGEfab’s first phase that stores an animation, after its first release. It fits D2

In return EDGEdir’s extension API gives EDGEfab a search of the index, the animations a character’s entity carries among them, in D2. Its shape goes to EDGEfab #7 before it is built.

What EDGEdir asked for, as the request to EDGEfab put it:

Need Why
A Library kind for a single animation, with asset.json; Add to Library and Add to Project; an id that stays with the animation in both places So the index can find it, and a clip can name it wherever it lives
The clip as glTF on the game rig’s bone names, with the rig’s game path, the length, the frame rate, whether it has root motion and whether it loops To preview it, fit it to actors and lay it out on the lane
Once #14’s import exists: the same clip as a game .anims in the item’s source/archive. Agreed 2026-11-16: the conversion to the game’s format is EDGEfab’s So EDGEdir packs it without doing the low-level conversion itself, and EDGEquest can use it too
Retargeting to the game’s other rigs, as EDGEfab’s own feature So one made clip can serve actors of several builds

Clips on an actor track

Transitions

A transition is a clip that sits over the join of two animation clips. Three methods:

Method How New frames? Reaches the game by
Blend (first) Crossfade the end of clip A into the start of clip B over the transition’s length: each bone’s rotation by slerp, positions by lerp, on an ease curve. Root motion is matched first, so feet do not slide apart In the preview only The workspot’s own blend time on the jump (unverified: whether a jump blends, and for how long). Or baked
Inertial Clip B plays from its start, and the difference from A’s last pose and speed decays away. Keeps B’s motion whole; good for short joins Yes Baked
AI A provider makes the frames between A’s last poses and B’s first Yes Baked

“Baked” means EDGEdir samples the actor’s track into new animation frames, writes them as glTF, and REDbridge imports them into a new .anims. This needs REDbridge #14’s import, which does not exist yet. So the first transitions that play in the game are the game’s own blends, and EDGEdir’s preview must be honest about the difference: a transition shows a mark when the game will not play what the preview shows.

The owner’s rule (2026-11-16): tweening and an AI provider are both options on every transition. The method is a field of the clip, so a transition can be made one way, judged in the preview, and made again the other way. A made transition keeps its frames beside the scene (under the scene’s folder, as EDGEwave keeps generated audio in <name>.gen/), with a note of the method, provider and settings that made it.

About the AI method: no provider with an API for in-betweening on a custom skeleton is verified. General text and image models do not make joint rotations well. Uthana, which EDGEfab will use for single clips, lists video to motion, text to motion, locomotion, retargeting and a GraphQL API with GLB output on its page (read 2026-11-16), but nothing for blending or in-betweening two motions. This is research (D7), and Blend and Inertial are the dependable methods. The key would be kept in VS Code’s secret store, set by a command, as EDGEwave and EDGEfab do.

Sequences

Agreed with the owner on 2026-11-16: animations sequenced together with their transitions are a thing that is stored and edited. The shape below was agreed the same day (Q8).

A sequence is a run of animation clips and transitions for one actor, saved under its own name: for example “walk in, sit, lean back”. It is not tied to a scene or a character, only to a rig, so it can go on any actor with that skeleton.

Point Proposal
File <name>.edgeseq, JSON: the rig, and the same clips list an actor track holds, starting at time 0
Making one Select clips on an actor track, Save as Sequence. Or New Sequence, which opens the same editor with one actor track and a stand-in body
Using one Drag it from the Desk or Library onto an actor lane. It shows as one block. Opening the block edits the sequence
Linked or copied Linked by default: a change to the sequence shows in every scene that uses it. Unpack turns the block into plain clips on the lane
Storing On the Desk and in the Library like a scene, as kind sequence
In the game Nothing new: when a scene is packed, a sequence is its clips. Once baking exists (D7), a sequence can also be baked once into a single animation and reused

Sets: the stage from EDGEbuilder

Agreed by the owner on 2026-11-17 (all six questions as recommended), from the owner’s note of the same day. The part that needs no game is built as D5a (EDGEdir 0.0.17): see D5’s plan, “What is built”. The owner’s words for the split: EDGEbuilder and EDGEdir both say “scene” and mean the same place and moment, but each gives a different part of it.

  EDGEbuilder’s scene EDGEdir’s scene
Is The stage: what exists in the world. Props, people, vehicles, lights The direction: what those things do over time
Answers What is there, and where What do they do, where do they go, what sounds play, and when
File <name>.scene.json (its scene format) <name>.edgedir
Called, in EDGEdir A set A scene

One set can have many scenes: the same alley, directed three ways. That is why EDGEdir’s Library kind is act.

The flow

The owner’s proposal: EDGEbuilder’s scenes show in EDGEdir as a view, and choosing one opens it in EDGEdir’s editor with a track for each person and vehicle on it.

Step What happens
The Sets view Lists EDGEbuilder’s scenes by their .scene.json ending: in any folder of the Library, and in the open REDcode project’s source/scenes. Each row shows the name and how many people and vehicles it has. Not EDGEbuilder’s “This PC” scenes: they are in its package’s data folder, which is its Desk, and no tool reads another’s Desk (the Library’s rules; confirmed by EDGEbuilder on 2026-11-17). The walk of the Library skips what EDGEbuilder’s own skips: folders ending .bake (a bake can hold copies of scenes) or .asset, folders starting with a dot, and node_modules; it stops 8 folders deep
New Scene on This Set Makes a scene on the Desk and opens it. The scene names the set. It gets one actor track for each npc object, with the actor (record and appearance) and the mark taken from the set, and one vehicle track for each vehicle. The tracks are empty: a person with no clips stands idle, as EDGEbuilder left them
A set that has scenes The view shows its scenes under it. Choosing one opens it; New Scene on This Set makes another
Choose Set A scene made without a set can be given one later, and a set can be taken off. Tracks made by hand stay
Point Rule
The set stays EDGEbuilder’s EDGEdir reads the file and never writes it. People and props are placed and moved in EDGEbuilder
A link, not a copy The scene keeps the set’s place and content hash: "set": { "path": "<Library or project path>", "name": "My Alley", "hash": "sha256:..." }. A track that came from the set keeps the object’s id: "from": "wakako_spot"
When the set changes On opening the scene, EDGEdir reads the set again. A person who moved has a new mark. A new person is offered as a track. A track whose person is gone says so and keeps its clips. Each change is one edit that can be undone, as a sequence’s refresh is
Where the scene plays A scene with a set plays where the set is: the anchor is the set’s place in the world ("anchor": { "mode": "set" }), not in front of V. Marks are the set’s world positions
Actors not in the set Allowed. An actor added in EDGEdir stands at a mark typed in EDGEdir and is spawned by the scene. EDGEdir does not add them to the set
A set that cannot be found The scene opens, says the set is missing, and keeps the marks it last read. A set renamed in the Library is lost this way, since EDGEbuilder’s scenes have no id (asked for in the request below)

In the preview

Step Shows
First Each person at their mark from the set, facing as placed. Each prop as a grey box of its size: the set’s file carries every object’s bounds, so nothing is exported
Later The props’ real meshes, exported once through REDbridge and cached, as bodies are. EDGEbuilder’s plan has the same need for its sector view (its E2), so the cache may be shared (unverified)

In the game

Point What it means
The props REDnode’s world.load spawns the set’s meshes, entities and people. Where the set is baked into a mod and installed, the props are already there and are not loaded twice (EDGEbuilder’s “baked and on” flag)
The people the scene directs REDnode plays a workspot only on a person spawned with it. So the scene’s player spawns each directed person itself, with its written workspot, at the set’s mark, and the set must load without them. world.load has no way to leave objects out today (unverified). The owner asked whether REDnode could find a person who is already there and direct them. Finding is not what stops it (world.near finds people): a workspot plays only on a person who carries it, and the person gets it when spawned. Whether a person can be directed through a small object beside them that carries the workspot is unverified; REDnode names that way for V on its #47. Asked as REDnode #48: if it works, the scene takes a set’s people over where they stand; if not, world.load leaves them out and the scene spawns them
A baked set’s people EDGEbuilder does not bake people (its “Baking NPCs is open”), so today people come only from the loaded set or the scene. If they are baked one day, the scene must be able to take one over by its ref (unverified, later)

Vehicles

EDGEbuilder’s plan has no vehicle kind (checked 2026-11-17): a vehicle’s .ent can be dropped as a plain entity, and whether that gives a working vehicle is unverified. Requested of EDGEbuilder the same day: a vehicle kind picked from the game’s Vehicle.* records, as npc is from Character.*.

In EDGEdir a vehicle gets its own track kind, vehicle. What a clip on it can be is not designed yet, and nothing of it has been tried in the game:

A vehicle might Route in the game
Stand, with its engine and lights on or off Unverified
Open and close doors Unverified
Drive from one mark to another Unverified; the game’s AI drives vehicles along lanes
Play an animation of its own (an AV landing; the game has such sets for quest scenes) Unverified; REDnode’s Director spike lists it as an optional step
Carry an actor Unverified; it needs the game’s mounting

So the vehicle track needs a REDnode spike before it has a plan. Until then a set’s vehicles show in the preview as boxes and stand in the game where EDGEbuilder put them.

Where it goes in the phases

Part Phase
The Sets view, New Scene on This Set, the link, marks from the set, props as boxes The first part of D5 (it needs no game, and D5 needs the place a scene plays at)
The set loaded in the game around the scene’s people D5
Props’ real meshes in the preview After D6
The vehicle track Its own phase after D6, once EDGEbuilder has the kind and REDnode’s spike says what a vehicle can be told to do

Questions and the owner’s answers

All agreed as recommended on 2026-11-17.

# Question Agreed
S1 In EDGEdir, is an EDGEbuilder scene called a set (the view is Sets), so the two “scenes” are never mixed up on one screen? Yes
S2 Is the set linked and read only in EDGEdir, with many scenes allowed for one set? Yes
S3 Does every person and vehicle of the set get a track at once, though most may stay empty? Yes, as the owner proposed: an empty track is an extra who stands idle
S4 May a scene have actors that are not in the set? Yes; EDGEdir does not write them into the set
S5 Is it built as the first part of D5? Yes
S6 The vehicle track: its own phase after D6, after the EDGEbuilder kind and a REDnode spike? Yes

Pins: named places from REDnode

Proposed on 2026-11-18, from the owner’s note of the same day. N1 to N3 were agreed that day with EDGE Director’s plan (its R5), and pins are built as its part DR3: the first part is built (the document’s side and the Director’s, EDGEdir 0.0.26), described under that plan’s “What is built”, which is the truth where it differs from this section. N4 to N6 were agreed as recommended on 2026-11-18. The owner’s idea: pins are named places a scene’s timeline can use, for example to spawn at, to walk to, and to trigger when V is near.

What a pin is today

REDnode’s world pins (its #43, passed in the game on 2026-11-14, closed):

Fact From
A pin is a title, an optional line of text, a place in the world (x, y, z) and a look. It has no id and no facing REDnode’s packages/overlay/pinsets.js
The Pins window in the game lists every pin with its distance and Go there, and has Drop a pin here: a pin at V’s place with a typed name REDnode’s docs/world.md, “WP3: build”
A set of pins is one file, <name>.pins.json ("format": "rednode-pins", version 1, up to 200 pins). The player’s own sets are in %APPDATA%\@rednode\overlay\pins; a file opened from elsewhere, such as a mod project, stays where it is The same
A package draws pins with world.pin, and loads a file with world.pinSet.load. Pins only draw: they need no permission The same

So a modder can already walk the location in the game, drop a pin at each spot, and have a file of named places. EDGEdir reads that file.

What a scene does with pins

Use In the document Needs
The scene’s place "anchor": { "mode": "pin", "pin": "<title>" }: the scene plays at that place on the map, with no set. Marks are metres from it, as today A small change to the player. This is the way a scene with no set gets a fixed place
A mark at a pin An actor’s mark names a pin: "at": { "pin": "<title>", "yaw": 90 }, with an optional offset in metres. On a set too Nothing in the game: the cue sheet carries the numbers
A shot at a pin, or aimed at one With D6c’s camera: "at": { "pin": ... }, "aim": { "pin": ... } D6c
Start when V is near "start": { "near": { "pin": "<title>", "radius": 8 } }: the player spawns the cast out of view, waits, and starts the clock when V comes within the radius The player watches V’s place itself (a few times a second). In a mod a player installs (D7), the game’s own trigger areas are the better way: EDGEquest’s and EDGEbuilder’s ground (EDGEbuilder #3)
Walk to a pin A move clip on an actor’s track: "move": { "to": "<title>", "gait": "walk" }. The person leaves their workspot, walks, and takes it up again at the next clip A REDnode call that sends a spawned person walking (unverified: REDnode gives a hold command through the game’s AI commands today; a move command on our spawned people has not been tried). The clip’s length is a guess from the distance; the game decides when the person arrives
Wait in the middle A hold on the timeline: the clock stops until V is near a pin, or the walk has arrived A change to the timeline’s model: part of it waits for an event. Later, after the first three
Point Rule
The file stays REDnode’s and the player’s EDGEdir reads it and never writes it. Pins are dropped, named and removed in the game’s Pins window
A link, as a set’s is "pins": { "path": "...", "name": "...", "hash": "sha256:..." }, one file for a scene. The scene keeps the places it last read, so it still opens when the file is gone
A pin is named by its title Pins have no id. Two pins with one title in a file: EDGEdir takes the first and says so. A pin renamed in the game is lost to the scene, which says so and keeps the place (an id is asked of REDnode, below)
When the file changes EDGEdir watches it. A moved pin moves every mark, shot and the origin that name it, as one edit that can be undone
With a set A scene may have both. The set gives props and people; pins give places nobody stands on yet

Adjusting in the game

The owner wants to adjust a scene while standing in it. Pins give a first way with nothing new in the game:

Step Where
Play the scene Play in Game, in VS Code
Walk to where an actor should stand, and drop a pin, or drop one again under the same name The Pins window, in the game
The mark moves in the open scene EDGEdir, by itself, when the file changes
Play again Play in Game

The owner asked on 2026-11-18 for more than this: an app of EDGEdir’s own in the game, EDGE Director, that opens, plays and adjusts a scene there. Its plan is EDGE Director; pins are one part of it (DR3).

In the preview and in the game

Where Shows
The preview Each pin as a small post with its title, at its place from the scene’s origin. Pins far from the origin are listed, not drawn
The editor A Pins section in the scene’s inspector: the file, its pins, which are used. A pin picker where a mark is typed
The game, at Play in Game The player draws the scene’s pins with world.pin while it runs, so the modder sees the names in the world. They go when the player stops

Parts

Part Builds Needs the game
Pins 1 The link, Choose Pins, marks and the scene’s place at a pin, the preview, the watch For the test only
Pins 2 Start when V is near For the test only
Pins 3 Walk to a pin A REDnode spike first

Questions and the owner’s answers

All agreed as recommended on 2026-11-18 (N1 to N3 with EDGE Director’s plan, N4 to N6 after).

# Question Agreed
N1 Are pins REDnode’s .pins.json files, read and never written by EDGEdir? Yes
N2 May EDGEdir list the player’s own sets from REDnode’s folder (%APPDATA%\@rednode\overlay\pins), read only, beside pin files in the open project? Yes: that is where Drop a pin here puts them. REDnode agreed on its #50 (2026-11-18): read only, and watched. Only sets the player made are there (a set opened from elsewhere stays where it was); check the format and version 1, ignore fields not known; a save is a .tmp file, then a rename
N3 One pin file for a scene? Yes, at first
N4 “Trigger when near” is first the scene’s start, with waits in the middle later? Yes
N5 Pins 1 before D6, since it gives a scene its place on the map and the adjust loop? Yes: it is small and needs no new call
N6 Walk to a pin waits for a REDnode spike, and is planned after it? Yes

The editor

One custom text editor for *.edgedir, built the EDGEwave way: plain TypeScript, canvas, the whole document posted back on each change so undo, redo, save and the dirty mark are VS Code’s own.

Part What
Viewport (top) The 3D preview: the cast, the floor grid, marks and paths, the camera’s view or a free orbit view
Transport Previous edge, play, stop, next edge, loop, the time, Play in game
Lanes (bottom) A ruler in seconds and frames; one lane per track with its name, kind, mute and lock; clips as blocks with their names; the playhead
Inspector (side) The selected clip’s or track’s fields

Like EDGEwave: the colours and outlined buttons, the ruler, the transport, drag sideways to move a clip, drag up or down to reorder lanes, a splitter between the two halves.

Beyond EDGEwave, because a scene needs it: many clips per track, drag a clip’s edge to trim, snap to frames and to other clips’ edges, zoom and scroll in the lanes, select several clips, copy and paste, drop an animation from the Animations view onto a lane.

Views

View Shows Phase
Desk The scenes being worked on, and Recent D1
Library Scenes kept in the EDGE Library D7
Animations The game’s animations, searched by name, grouped by anim set and rig; a clip can be previewed and dragged to a lane. Later: the game’s workspots D2

A fourth view, Project, lists the open project’s scenes when a REDcode project is open (D7).

The Animations index is built from the game’s files through REDcode’s bridge and kept in the extension’s storage on the PC. It is never committed. EDGEdir owns it (Q1, agreed). It lists three sources: the game’s animations, the animations EDGEfab stored in the Library, and those in the open REDcode project (see “Animations and actors”). With an actor selected, it can show only the animations that fit that actor’s rig.

EDGEdir gives the index to other tools through its extension API (search by name, a clip’s set, rig and length), so EDGEfab and EDGEquest do not build their own.

Desk and Library

Place Where Holds
Desk %LOCALAPPDATA%\EDGEdir\desk\<name>.act.asset\ One folder per scene, shaped like a Library item: asset.json, the .edgedir under source/raw/edgedir/, files the scene brought in (sounds, videos) beside it, made files under source/archive
Library The shared root, <modder's folder>\<name>.act.asset\ The same folder, moved by Add to Library
Project source/raw/edgedir/<name>.edgedir in a REDcode project, with a came-from note in source/library.json (by: "edgedir") The scene, by Move to Project or Use in Project

New Scene makes a scene on the Desk and opens it. The Library’s rules are EDGEbuilder’s (docs/library.md), unchanged. EDGEbuilder’s Library already uses the kind scene, so EDGEdir’s kind word for a scene is act (agreed 2026-11-16): the folders above are <name>.act.asset. Only folder names and asset.json carry it; the UI says scene.

Into the game

What a packed scene is

File Made by What
<scene>.cues.json EDGEdir The cue sheet: the cast (record, appearance, mark, workspot), the anchor, the set, and every cue in time order
One .workspot per actor EDGEdir, through REDbridge cr2w calls The actor’s clips as named entries, with the anim sets they come from
One .anims per actor, when the track has baked frames REDbridge import (#14) The baked transitions or the whole baked track
Sounds and videos Copied The files the audio and video tracks use
A REDnode package EDGEdir, from a template Plays the cue sheet. Its rednode-app.json names the permissions it needs

The game files go into the project’s archive; REDcode packs it. The package ships beside it. A player needs REDnode and its frameworks.

Three routes for the timing

Route How Good Bad When
1. Cues from a package The package spawns the cast, then sets a timer per cue Works with REDnode nearly as it is 1 to 3 frames of jitter per cue; drifts in menus and slow motion; two actors can slip apart D5, the first that plays
2. REDnode’s scene player REDnode takes the whole cue sheet and runs it on the game thread, on game time Frame-true; pauses with the game; smooth camera moves A new REDnode feature Requested in D5, used when it lands
3. Baked tracks Each actor’s track is one long animation; one cue starts each actor The join between clips is exact, whatever the scheduler does Needs #14 import; a change means a new bake D7

Routes 2 and 3 work together: one start per actor, on the same frame. A fourth route, writing the game’s own .scene file so a quest can play the scene, is kept for later with EDGEquest (L1).

Play from VS Code

Play in game packs the scene to a scratch project, swaps its files into the running game, and tells REDnode to play it at V. The swap and the play order need REDnode’s editor channel to grow (a request). Access stays as that channel has it: this PC only, a bearer token made new each run, and an Allow in the game the first time a tool asks.

Requests this design leads to

Filed on 2026-11-16: REDnode #46 (the written-workspot spike and the weather), REDbridge #17 (export of chosen clips; anims.info is in its #14), EDGEfab #7 (the split and the animation item; answered and accepted the same day, see “Animations and actors”). REDnode took #46 the same day: the spike is built and runs in the game after the A2 test. REDbridge #17 was taken too, to ship with anims.info before D2. The rest are filed when their phase is planned.

The written-workspot spike ran in the game on 2026-11-16 (REDnode #46, its Director spike; REDnode’s results, not run by EDGEdir):

Asked Found
Does a written workspot play as a track? Yes, one per actor. Each clip is a sequence whose idle is the clip with loopInfinitely on, in a bare tree (the clips and a fast exit). Keeping the game’s full tree lets its exits take over
Does a jump blend? Yes. world.useWorkspot starts it; a jump with instant: true goes at once with a smooth blend. instant: false waits for the playing clip’s end, 20 s or more
How late are timed jumps? 0 to 13 ms, and two actors jump in the same frame
Still open Quest clips give a T pose that stays; a brief T pose at the first play; root motion moves nobody (0.00 m), so a walk needs the person moved by the scene
REDnode proposes next A short round on quest clips, then a REDnode call that writes the workspot (such as world.writeWorkspot({ clips }), shape to agree), so EDGEdir does not write game files itself

So the first route, cues from a package, holds. A clip that moves its actor needs the scene to move the person; that is D5’s to plan.

REDnode’s world.writeWorkspot passed in the game the same day (REDnode 0.66.9, in its next build; the shape is on REDnode #46):

Point What it means for EDGEdir
The call world.writeWorkspot(name, { rig, clips: [{ set, anim, name, loop }] }) writes one workspot and answers its path for world.spawn and its entries. world.jumpWorkspot(id, name) jumps at once. So EDGEdir writes no game files for an actor: its package passes each actor track’s animations
Quest clips Solved: the engine finds a workspot’s animation setup by a hash, and the call makes a new one. Quest clips and gameplay clips jump at once and loop
The brief T pose It comes at each person’s first play. So D5 starts every actor once while out of view, before the scene shows them
A jump before the person is in the workspot world.jumpWorkspot answers false. Call world.useWorkspot first
Trim, speed, loops A workspot’s entry has none. D5 cuts a clip short with a timed jump (out), and repeats one by jumping to it again. in (starting inside an animation) and speed have no route yet: until one is found they are for the preview, and Play says so
Root motion Confirmed as not applied: the actor moved 0.00 m. The scene moves the person
Needs The bridge and archives permissions for EDGEdir’s package
To Need For phase
REDnode The A2 test’s result, and a spike on a written .workspot (shared with its own “second spike”) D0
REDnode Editor routes: swap a scene’s files in, play a cue sheet, stop, report the time D5
REDnode A scene player on the game thread and game time (route 2), with a camera in it D5, D6
REDnode Sound on an entity or at a place (its S2 Space) After D6
REDbridge anims.info (#14), and export of chosen clips from an .anims D2, D3
REDbridge .anims import from glTF (#14). Needed for made animations in the game, and for baked transitions. EDGEfab needs it too, so the request may be EDGEfab’s to make D5 for made animations, D7 for baking
EDGEwave A sound’s peaks and a mix’s length through its API D6
EDGEfab The split agreed in Q1: its plan drops the animation index and “blend two clips”. It imports animations and makes them from video, and stores each by itself in the Library, in the shape “Animations and actors” lists. Retargeting to the game’s other rigs D2
EDGEbuilder A vehicle kind in its scenes, from Vehicle.* records; an id in a scene file; where its scenes are found (EDGEbuilder #6, filed 2026-11-17) The vehicle track; the set’s link
REDnode A call on the editor channel that reaches a package’s service; directing a person not spawned with the workspot, or world.load leaving such people out (REDnode #48, filed 2026-11-17) D5
REDnode A spike on what a spawned vehicle can be told to do (not filed yet) The vehicle track
REDnode For pins: a call that sends a spawned person walking to a place, out of and back into their workspot; an id and a facing on a pin; reading the player’s pin sets from its folder (REDnode #50, filed 2026-11-18, see “Pins”) Pins 1 and 3
EDGEkit Include EDGEdir, once it is published After the first release

Phases

Each phase ends with a hand test by the owner, and an in-game test where it changes the game. Each gets its own plan, agreed before it is built.

Phase Builds Test proves
D0 Spikes No features. (d) Setting and giving back the weather through REDnode. (a) A .workspot written through REDbridge with clips from two anim sets, on a spawned NPC: does it play, does a jump blend, what happens in a gap, how late are timed jumps. (b) A character GLB and two clips from another GLB playing in a three.js webview. (c) What EDGEfab and EDGEdir each own The route for D3 and D5 is known, or changed
D1 Timeline The .edgedir document and its editor: tracks, clips as blocks with typed-in lengths, move, trim, snap, zoom, undo. New Scene, the Desk view and folder A scene with three tracks is made, edited, closed and opened again from the Desk
D2 Cast and clips The Animations view and its index, with the game’s animations, the Library’s and the open project’s; the actor picker; drag an animation to a lane with its true length; the rig check; swap a track’s actor; trim, speed and loop A named NPC has two real game clips in a row on its track; the track’s actor is swapped for another of the same rig and keeps them; a clip for another rig is marked unfit; V can be picked. Plan: D2
D3 Preview The viewport: actors’ bodies playing their tracks, scrub and play, marks (built, EDGEdir 0.0.9; root motion paths were left out, see its plan) Two actors play their clips in the viewport, in time with the playhead
D4 Transitions and sequences Transition clips with Blend and Inertial, in the preview; the method field with AI listed as not available yet. Save as Sequence, sequences on the Desk, a sequence as a block on a lane Two clips with a transition view as one movement; saved as a sequence, they go onto a second actor in another scene
D5 Play in game The cue sheet, the written workspots, the player package (route 1), Play in game The D4 scene plays on real NPCs in front of V, and the tester notes how far it is from the preview
D6 Audio, camera, weather Audio tracks (events, files, EDGEwave mixes), camera tracks (cuts) and the weather track, in the preview and the game A scene with two actors, a line of sound, three shots and a change to rain plays in both, and the weather comes back after
D7 Pack, Library, baked Move to Project, Add to Library, the Library and Project views, a packed mod a player installs. Baked tracks (route 3) when #14’s import exists. Research into an AI provider for transitions A packed scene plays on a clean install; a baked transition matches the preview
D8 Script, video, MCP Script and video tracks; MCP tools (dir_*) so an assistant can read and edit a scene A script cue fires on time; an assistant adds a clip
D9 AI track Whatever Q7 decides, with its own plan To be set with the plan

Later, not planned: L1 export to the game’s .scene with EDGEquest; camera moves and curves; faces and lipsync; synced sets for two actors; walking an actor to a point; keyframes of EDGEdir’s own.

D1 needs nothing from another repo and can start as soon as this design is agreed. D0 runs beside it, because its in-game parts wait on REDnode’s A2 test.

Questions and the owner’s answers

All answered on 2026-11-16.

# Question Answer
Q1 EDGEfab’s plan has an animation index and clip tools, with “blend two clips” among them. Who owns what? Agreed 2026-11-16. EDGEdir owns the animation index, and the sequencing of animations with transitions as a thing that is stored and edited. EDGEfab owns the low-level work: making single clips, with AI providers too (the owner’s example: Uthana’s video to motion), and testing them on character models. EDGEdir assembles NPCs and their animations into sequences and scenes. EDGEfab’s clips show up in EDGEdir’s Animations view. EDGEfab’s plan still lists the index and “blend two clips”: it needs a request issue there
Q2 Is the document called a scene, though the game and EDGEbuilder use the word? Agreed: yes in the UI. The file is .edgedir. Checked after the answer: EDGEbuilder’s Library already uses the kind scene (docs/library.md), so EDGEdir’s scene needs another kind word. The kind is act, giving <name>.act.asset (agreed the same day). A sequence’s kind is sequence
Q3 Is a first in-game play with visible limits (route 1: slight jitter, the game’s own blends) acceptable in D5, with frame-true play to follow? Agreed 2026-11-16: yes
Q4 Are the REDnode and REDbridge requests in the table above agreed in principle? Agreed: D0’s and D2’s now (REDnode: the A2 result and the written-workspot spike; REDbridge: anims.info and export of chosen clips). The rest when their phase is planned
Q5 Which AI provider did the owner have in mind for transitions? Answered 2026-11-16: none yet, and it is not known whether plain tweening is enough. Both must be options on a transition. Tweening (Blend, Inertial) is built in D4; the provider is research, and the method is in the document format from the start
Q7 What does the AI track do? Agreed as the direction: the smallest useful form, a prompt to REDagent whose answer is shown or spoken as a line, inside a window of time. To be settled before D8, so the script track is built to carry it
Q8 Is a sequence, as the “Sequences” section draws it, what the owner meant by a storable and editable thing: its own file, reusable on any actor with the same rig, linked into scenes? Agreed: yes
Q6 The views: Desk, Library, Animations, and Project when a project is open? Agreed: yes

Out of scope

Making and changing single animation clips, by hand or by an AI provider such as video to motion, and testing them on a character (EDGEfab). Quest logic, dialogue choices and lines (EDGEquest). Mixing sound (EDGEwave). Placing props (EDGEbuilder). Faces and lipsync, until a way is found.