Writing scenes

A scene is one small TypeScript file. It says which body, clip, room and controls the scene has, and how the body reacts when you touch it. You need no build tool: DGen reads the file as it is.

Your scenes folder

Each profile has a scenes folder: scenes in your DGen folder by default. The Scenes tab of the config shows it, and open opens it. DGen writes into it:

Open the folder in an editor such as VS Code and start from my-scene.ts. Sounds go in a sounds folder beside your scenes.

Let your coding agent write it

Open a coding agent (Claude Code, Codex, Cursor) in your scenes folder and ask for the scene you want, in your own words. AGENTS.md tells it everything: the rules, every builder, the hooks, how to check a file. For example: "a scene where the body smiles when I stroke its arm and looks at my hand when it comes near the face".

Try a scene

1. Save the file in your scenes folder.
2. In the studio, pick it in the scene list (reload the page after an edit).
3. If it fails, the error shows over the scene list with the file and the line.

The scene API

A scene file

• One .ts file in this folder is one scene. Its file name is its name in the page (my-scene.ts opens as scene=my-scene): lower case letters, digits and dashes. A name that is one of DGen's own scenes opens as ~<name>, marked "(yours)".
• Its one import is import type { Dgen } from 'dgen'. It imports nothing at runtime: the server refuses any other import, naming the file and the line. Everything comes through dgen.
• Its default export is a function of dgen that returns dgen.scene({...}). The builders only describe: nothing runs until the page opens the scene and its events fire.
• Sounds are files of sounds/ in this folder.

The builders of dgen

The keys of dgen.scene

Only title and body (or bodies) are needed. Clip, room, object, hooks and music are for Genesis 9 bodies.

Controls

A control is a value the user picks on the page: dgen.choice(id, options) put where the value goes, for example look: dgen.choice('surface', { flesh: dgen.skin(), latex: dgen.surface('latex', { tint: [0.6, 0, 0.1] }) }) on dgen.letters, or layout: dgen.choice('layout', ['anemone', 'spiral']) on a wall. The page draws each control the scene uses, under the scene's name, and keeps the pick in the url under its id. An id must be unique in the scene.

Hooks

dgen.on(event, filter, (e, scene) => ...). A touch event's filter may be left out (it then takes any touch).

• Touch events (touch, press, grab, pinch, stroke, release): filter { on, by, tool }, each one value or a list. e: on, side (L, R or undefined on the middle), by, tool, at (the point, m), hard (0 to 1), held (s).
• Near events (near, away): filter { on, within, by }, within in m and needed. e: on, side, by, at, distance (m).
• Time events (after, every): filter { seconds }, needed. e: time.
• on: a region of the body (head, neck, chest, breasts, waist, hips, butt, thighs, knees, calves, feet, upper arms, forearms, hands) or object.
• by: pointer, left hand, right hand, object, bar. A VR hand fires what the mouse fires.
• tool: press, grab, pinch.

What a hook's function acts on, scene (the selected body):

A hook that throws shows its event and its message over the stage for 6 s; the other hooks go on.

What throws

The builders, or the page as it opens the scene, throw naming the value and the valid ones on: a slider out of its range, a worn piece that does not read, a place that is not two or three numbers, an unknown event, region, by or tool, a near hook with no within, a time hook with no seconds, an object size out of its range, a sound that is not a file of sounds/ or whose volume is not 0 to 1, a third bar, a control with no option or a def that is not one of them, an asset id that is not one of the ids or a need that is not mandatory or optional, an about empty, of two lines or past 120 characters, no tag or a tag that is not one of them. The page shows the error over the scene list.

Check a scene

1. Types: this folder has a tsconfig.json. bun check here (Bun 1.4 or later), or npx tsc -p ., names each wrong value with its file and line, and nothing when every scene compiles.
2. The server: curl -s http://localhost:<port>/api/scenes/<name>.js (the address DGen opened) answers the scene as JavaScript, or why it is refused (an import, a syntax error and its line).
3. The page: pick the scene in the scene list at the top. Reload the page after an edit.

Every body is an adult

A character whose name or product says young, teen, child or kid is refused, whatever its pack. Never write a scene that makes a body look young.

The example (my-scene.ts, written when the folder was new)

import type { Dgen } from 'dgen'

// a scene: one file of this folder, its name the scene's (lower case letters, digits and dashes). It imports nothing
// but the type of dgen; open the folder in an editor for its autocompletion. Pick it in the scene list at the top.
// Its hooks run when the body is touched; its sounds are files of sounds/ beside it: dgen.sound('my-music.mp3')
export default (dgen: Dgen) =>
    dgen.scene({
        title: 'My scene',
        // what it is, for the scene list: one line, and the words that sort and find it
        about: 'A body that smiles when stroked and is surprised when pinched',
        tags: ['interactive', 'adult'],
        body: dgen.genesis9({ shape: { size: 0.8, butt: 0.6 } }),
        // the Daz products it uses beyond Genesis 9 Starter Essentials: an optional one it runs without (the grin
        // below then keeps the face still), a mandatory one it does not open without; the page lists the ones your
        // library lacks, with where to get them
        assets: { 'expression-fusion': 'optional' },
        hooks: [
            // a smile for three seconds when the body is stroked (the Press tool, dragged along the skin)
            dgen.on('stroke', (_, scene) => scene.emotion('smile', { for: 3 })),
            // surprised at a pinch
            dgen.on('pinch', (_, scene) => scene.emotion('surprised', { for: 1.5 })),
            // a grin at a grab, a face of Expression Fusion
            dgen.on('grab', (_, scene) => scene.emotion('ef10', { for: 2 })),
        ],
    })