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:
- The Animations view can filter by the selected actor’s rig.
- An animation dropped on an actor with the same rig just plays.
- On another rig, EDGEdir warns and shows the clip as unfit. It does not retarget: changing a clip to fit another skeleton is low-level work, so it is EDGEfab’s (a request).
- The same animation can be on many actors and in many scenes. Swapping a track’s actor for another with the same rig keeps every clip.
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:
- A Desk is one tool’s own, by the Library’s rules. EDGEdir sees an EDGEfab animation only once it is in the Library or in the open project, not while it is on EDGEfab’s Desk.
- A made animation plays in EDGEdir’s preview as soon as it is in the Library. It plays in the game only once REDbridge can import animation frames (#14). Until then a scene that uses one says so at Play and Pack. The game’s own animations are not held back by this.
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
- Clips do not overlap, except under a transition.
- Where a clip starts. By default a clip starts from where the last one left the actor (root motion carries on), so a walk followed by a sit ends up where the walk went. A clip can instead be pinned to a mark. The preview shows the path on the floor.
- A gap between clips holds the last pose in the preview. What the game does in a gap is for spike D0.
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 |
The link
| 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 |
The link
| 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.