-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathCO_WRITING_API_DOCS.html
More file actions
1855 lines (1594 loc) · 88.1 KB
/
CO_WRITING_API_DOCS.html
File metadata and controls
1855 lines (1594 loc) · 88.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Dream-E Co-Writing Mode — API & Feature Documentation</title>
<style>
/* ================================================================
GLOBAL RESET & BASE TYPOGRAPHY
================================================================ */
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
:root {
--bg: #0f1117;
--bg-surface: #171923;
--bg-surface2: #1e2130;
--bg-code: #131520;
--border: #2d3148;
--border-light: #3a3f5c;
--text: #e2e4ea;
--text-muted: #8b8fa4;
--text-dim: #5a5e76;
--accent: #8b5cf6;
--accent-light: #a78bfa;
--accent-bg: rgba(139, 92, 246, 0.08);
--blue: #6c8aff;
--green: #4ade80;
--teal: #2dd4bf;
--red: #ef4444;
--yellow: #facc15;
--pink: #f472b6;
--orange: #fb923c;
--mono: 'Cascadia Code', 'Fira Code', 'JetBrains Mono', 'Consolas', monospace;
--sans: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
--sidebar-w: 260px;
}
html { scroll-behavior: smooth; font-size: 15px; }
body {
background: var(--bg);
color: var(--text);
font-family: var(--sans);
line-height: 1.7;
display: flex;
min-height: 100vh;
}
a { color: var(--accent-light); text-decoration: none; transition: color .15s; }
a:hover { color: var(--accent); text-decoration: underline; }
::selection { background: rgba(139, 92, 246, 0.35); color: #fff; }
/* ================================================================
SIDEBAR NAVIGATION
================================================================ */
nav.sidebar {
position: fixed;
top: 0; left: 0;
width: var(--sidebar-w);
height: 100vh;
overflow-y: auto;
background: var(--bg-surface);
border-right: 1px solid var(--border);
padding: 24px 0;
z-index: 100;
scrollbar-width: thin;
scrollbar-color: var(--border) transparent;
}
nav.sidebar .logo {
display: flex;
align-items: center;
gap: 10px;
padding: 0 20px 18px;
border-bottom: 1px solid var(--border);
margin-bottom: 16px;
}
nav.sidebar .logo svg { flex-shrink: 0; }
nav.sidebar .logo span {
font-weight: 700;
font-size: 1.15rem;
background: linear-gradient(135deg, var(--accent-light), var(--blue));
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}
nav.sidebar .logo small {
display: block;
font-size: 0.7rem;
font-weight: 400;
color: var(--text-muted);
-webkit-text-fill-color: var(--text-muted);
}
nav.sidebar ul { list-style: none; }
nav.sidebar > ul > li > a {
display: block;
padding: 7px 20px;
font-size: 0.88rem;
font-weight: 600;
color: var(--text-muted);
transition: all .15s;
}
nav.sidebar > ul > li > a:hover,
nav.sidebar > ul > li > a.active {
color: var(--accent-light);
background: var(--accent-bg);
text-decoration: none;
}
nav.sidebar > ul > li > ul { padding-left: 16px; }
nav.sidebar > ul > li > ul > li > a {
display: block;
padding: 4px 20px;
font-size: 0.8rem;
color: var(--text-dim);
transition: all .15s;
}
nav.sidebar > ul > li > ul > li > a:hover {
color: var(--accent-light);
text-decoration: none;
}
/* ================================================================
MAIN CONTENT AREA
================================================================ */
main {
margin-left: var(--sidebar-w);
flex: 1;
max-width: 920px;
padding: 40px 48px 120px;
}
/* ================================================================
HEADINGS
================================================================ */
h1 {
font-size: 2.2rem;
font-weight: 800;
margin-bottom: 8px;
background: linear-gradient(135deg, var(--accent-light), var(--blue));
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}
h1 + .subtitle {
font-size: 1rem;
color: var(--text-muted);
margin-bottom: 32px;
}
h2 {
font-size: 1.55rem;
font-weight: 700;
color: var(--accent-light);
margin-top: 56px;
margin-bottom: 16px;
padding-bottom: 8px;
border-bottom: 2px solid var(--accent-bg);
}
h3 {
font-size: 1.18rem;
font-weight: 600;
color: var(--text);
margin-top: 32px;
margin-bottom: 10px;
}
h4 {
font-size: 0.95rem;
font-weight: 600;
color: var(--text-muted);
text-transform: uppercase;
letter-spacing: 0.06em;
margin-top: 24px;
margin-bottom: 8px;
}
/* ================================================================
PARAGRAPHS, LISTS, INLINE CODE
================================================================ */
p { margin-bottom: 14px; }
ul, ol { margin-bottom: 14px; padding-left: 22px; }
li { margin-bottom: 4px; }
li::marker { color: var(--accent); }
code {
font-family: var(--mono);
font-size: 0.88em;
background: var(--bg-code);
border: 1px solid var(--border);
border-radius: 4px;
padding: 1px 6px;
color: var(--blue);
}
/* ================================================================
CODE BLOCKS
================================================================ */
pre {
background: var(--bg-code);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px 20px;
margin: 14px 0 18px;
overflow-x: auto;
font-family: var(--mono);
font-size: 0.84rem;
line-height: 1.6;
color: var(--text);
}
pre code {
background: none;
border: none;
padding: 0;
font-size: inherit;
color: inherit;
}
/* Syntax highlighting hints */
pre .kw { color: var(--accent-light); }
pre .str { color: var(--green); }
pre .cmt { color: var(--text-dim); font-style: italic; }
pre .num { color: var(--orange); }
pre .fn { color: var(--blue); }
/* ================================================================
TABLES
================================================================ */
table {
width: 100%;
border-collapse: collapse;
margin: 14px 0 20px;
font-size: 0.9rem;
}
thead th {
background: var(--bg-surface2);
color: var(--text-muted);
font-weight: 600;
text-transform: uppercase;
font-size: 0.78rem;
letter-spacing: 0.05em;
padding: 10px 14px;
text-align: left;
border-bottom: 2px solid var(--border);
}
tbody td {
padding: 10px 14px;
border-bottom: 1px solid var(--border);
vertical-align: top;
}
tbody tr:nth-child(even) { background: rgba(255, 255, 255, 0.015); }
tbody tr:hover { background: var(--accent-bg); }
td code { font-size: 0.85em; }
/* ================================================================
COLLAPSIBLE DETAILS/SUMMARY (command reference)
================================================================ */
details {
background: var(--bg-surface);
border: 1px solid var(--border);
border-radius: 8px;
margin: 10px 0;
transition: border-color .2s;
}
details[open] { border-color: var(--accent); }
details summary {
padding: 12px 16px;
cursor: pointer;
font-weight: 600;
font-size: 0.95rem;
color: var(--text);
list-style: none;
display: flex;
align-items: center;
gap: 10px;
user-select: none;
transition: background .15s;
}
details summary:hover { background: var(--accent-bg); }
details summary::before {
content: '\25B6';
font-size: 0.65rem;
color: var(--accent);
transition: transform .2s;
}
details[open] summary::before { transform: rotate(90deg); }
details .detail-body {
padding: 0 16px 16px;
border-top: 1px solid var(--border);
}
/* ================================================================
BADGES / TAGS
================================================================ */
.badge {
display: inline-block;
font-size: 0.72rem;
font-weight: 600;
padding: 2px 8px;
border-radius: 4px;
text-transform: uppercase;
letter-spacing: 0.04em;
vertical-align: middle;
}
.badge-required { background: rgba(239, 68, 68, 0.15); color: var(--red); border: 1px solid rgba(239, 68, 68, 0.3); }
.badge-optional { background: rgba(139, 92, 246, 0.1); color: var(--accent-light); border: 1px solid rgba(139, 92, 246, 0.25); }
.badge-node { background: rgba(108, 138, 255, 0.12); color: var(--blue); border: 1px solid rgba(108, 138, 255, 0.3); }
.badge-edge { background: rgba(244, 114, 182, 0.12); color: var(--pink); border: 1px solid rgba(244, 114, 182, 0.3); }
.badge-green { background: rgba(74, 222, 128, 0.12); color: var(--green); border: 1px solid rgba(74, 222, 128, 0.3); }
/* ================================================================
NOTE / INFO BOXES
================================================================ */
.infobox {
padding: 14px 18px;
border-radius: 8px;
margin: 14px 0 18px;
font-size: 0.9rem;
}
.infobox-purple {
background: var(--accent-bg);
border: 1px solid rgba(139, 92, 246, 0.25);
color: var(--accent-light);
}
.infobox-blue {
background: rgba(108, 138, 255, 0.06);
border: 1px solid rgba(108, 138, 255, 0.2);
color: var(--blue);
}
.infobox-green {
background: rgba(74, 222, 128, 0.06);
border: 1px solid rgba(74, 222, 128, 0.2);
color: var(--green);
}
.infobox-yellow {
background: rgba(250, 204, 21, 0.06);
border: 1px solid rgba(250, 204, 21, 0.2);
color: var(--yellow);
}
.infobox strong { color: var(--text); }
/* ================================================================
NODE COLOR CHIPS (visual node type indicators)
================================================================ */
.node-chip {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 4px 10px;
border-radius: 6px;
font-size: 0.82rem;
font-weight: 600;
border: 1px solid;
}
.node-chip .dot {
width: 8px; height: 8px;
border-radius: 50%;
display: inline-block;
}
.chip-root { border-color: rgba(139, 92, 246, 0.4); background: rgba(139, 92, 246, 0.08); }
.chip-root .dot { background: var(--accent); }
.chip-plot { border-color: rgba(251, 146, 60, 0.4); background: rgba(251, 146, 60, 0.08); }
.chip-plot .dot { background: var(--orange); }
.chip-act { border-color: rgba(45, 212, 191, 0.4); background: rgba(45, 212, 191, 0.08); }
.chip-act .dot { background: var(--teal); }
.chip-char { border-color: rgba(244, 114, 182, 0.4); background: rgba(244, 114, 182, 0.08); }
.chip-char .dot { background: var(--pink); }
.chip-scene { border-color: rgba(108, 138, 255, 0.4); background: rgba(108, 138, 255, 0.08); }
.chip-scene .dot { background: var(--blue); }
.chip-comment { border-color: rgba(139, 143, 164, 0.4); background: rgba(139, 143, 164, 0.08); }
.chip-comment .dot { background: var(--text-muted); }
/* ================================================================
FIELD DESCRIPTION LISTS
================================================================ */
dl.fields { margin: 12px 0 18px; }
dl.fields dt {
font-weight: 600;
font-family: var(--mono);
font-size: 0.88rem;
color: var(--blue);
margin-top: 10px;
}
dl.fields dd {
margin-left: 0;
padding-left: 16px;
border-left: 2px solid var(--border);
font-size: 0.9rem;
color: var(--text-muted);
margin-top: 2px;
margin-bottom: 8px;
}
/* ================================================================
VOICE GRID
================================================================ */
.voice-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
gap: 8px;
margin: 12px 0 20px;
}
.voice-card {
padding: 8px 14px;
border-radius: 6px;
background: var(--bg-surface);
border: 1px solid var(--border);
font-size: 0.88rem;
font-weight: 500;
text-align: center;
color: var(--text);
transition: border-color .15s, background .15s;
}
.voice-card:hover {
border-color: var(--teal);
background: rgba(45, 212, 191, 0.05);
}
/* ================================================================
RESPONSIVE
================================================================ */
@media (max-width: 900px) {
nav.sidebar { display: none; }
main { margin-left: 0; padding: 24px 20px 80px; }
}
</style>
</head>
<body>
<!-- ================================================================
SIDEBAR NAVIGATION
================================================================ -->
<nav class="sidebar">
<div class="logo">
<svg width="28" height="28" viewBox="0 0 28 28" fill="none">
<rect width="28" height="28" rx="6" fill="#8b5cf6"/>
<path d="M7 14l4.5-6L14 11l3.5-5L21 14l-3 4H10L7 14z" fill="#fff" opacity="0.9"/>
<circle cx="14" cy="17" r="2.5" fill="#fff" opacity="0.6"/>
</svg>
<span>Dream-E<small>Co-Writing Mode Docs</small></span>
</div>
<ul>
<li><a href="#overview">1. Overview</a></li>
<li>
<a href="#node-types">2. Node Types</a>
<ul>
<li><a href="#node-story-root">Story Root</a></li>
<li><a href="#node-plot">Plot Node</a></li>
<li><a href="#node-act">Act Node</a></li>
<li><a href="#node-character">Character Node</a></li>
<li><a href="#node-scene">Scene Node</a></li>
<li><a href="#node-comment">Comment Node</a></li>
</ul>
</li>
<li>
<a href="#edge-types">3. Edge / Relationship Types</a>
<ul>
<li><a href="#edge-char-char">Character-to-Character</a></li>
<li><a href="#edge-act-plot">Act-to-Plot</a></li>
<li><a href="#edge-root-plot">Root-to-Plot</a></li>
</ul>
</li>
<li>
<a href="#api-reference">4. API Command Reference</a>
<ul>
<li><a href="#cmd-story-root">Story Root (2)</a></li>
<li><a href="#cmd-plots">Plots (4)</a></li>
<li><a href="#cmd-acts">Acts (4)</a></li>
<li><a href="#cmd-relationships">Relationships (4)</a></li>
<li><a href="#cmd-characters">Characters (2)</a></li>
<li><a href="#cmd-image-gen">Image Generation (1)</a></li>
</ul>
</li>
<li><a href="#context-system">5. Context System</a></li>
<li><a href="#image-generation">6. Image Generation</a></li>
<li><a href="#tts-voice">7. TTS / Voice Generation</a></li>
<li><a href="#storytelling-reference">8. Storytelling Reference</a></li>
</ul>
</nav>
<!-- ================================================================
MAIN CONTENT
================================================================ -->
<main>
<!-- ──────────────────────────────────────────────────────────────
1. OVERVIEW
────────────────────────────────────────────────────────────── -->
<h1 id="overview">Dream-E Co-Writing Mode</h1>
<p class="subtitle">API Reference & Feature Documentation — v2026.03</p>
<p>
<strong>Co-Writing Mode</strong> is a structured storytelling workspace in Dream-E designed for
authors who want to plan, outline, and develop a narrative <em>before</em> (or alongside) building
the interactive game graph. It provides dedicated node types for story structure—story root,
plot arcs, acts, and character relationship webs—plus an AI chat agent that can manipulate
all of these via a programmatic API.
</p>
<h3>How it differs from Game Mode</h3>
<table>
<thead><tr><th>Aspect</th><th>Game Mode</th><th>Co-Writing Mode</th></tr></thead>
<tbody>
<tr>
<td>Primary purpose</td>
<td>Build playable interactive fiction</td>
<td>Outline, develop, and structure a narrative</td>
</tr>
<tr>
<td>Canvas</td>
<td>Single canvas with all node types</td>
<td>Dual canvas system (Story + Character)</td>
</tr>
<tr>
<td>Unique nodes</td>
<td>Scene, Choice, Modifier, Comment</td>
<td>Story Root, Plot, Act, Character (plus Scene & Comment)</td>
</tr>
<tr>
<td>Edge types</td>
<td>Standard directed flow edges</td>
<td>Relationship edges with metadata (type, beginning, act developments, ending)</td>
</tr>
<tr>
<td>AI commands</td>
<td>Scene/entity/variable CRUD</td>
<td>All game-mode commands + 17 co-write commands</td>
</tr>
<tr>
<td>Player mode</td>
<td>Full adventure engine playback</td>
<td>N/A (narrative planning tool)</td>
</tr>
</tbody>
</table>
<h3>The Dual Canvas System</h3>
<p>
In co-write mode, a <strong>tab bar</strong> appears above the React Flow canvas with two tabs:
</p>
<ul>
<li>
<strong>Story Canvas</strong> — Shows <code>scene</code>, <code>comment</code>,
<code>storyRoot</code>, <code>plot</code>, and <code>act</code> nodes. This is the narrative
structure view where you lay out the overall story arc and plot lines.
</li>
<li>
<strong>Character Canvas</strong> — Shows <code>character</code> nodes only. These are
visual character cards linked to entities. Relationship edges between characters display on this
canvas, letting you map out the character web with detailed relationship data.
</li>
</ul>
<p>
Edges are filtered so that only edges whose <em>both</em> endpoints are visible on the current
canvas are shown. This prevents dangling connections from appearing when the other node lives on
the other canvas tab.
</p>
<div class="infobox infobox-purple">
<strong>Toolbar behavior:</strong> In co-write mode, the toolbar adapts to the active canvas.
On the Story Canvas you can drag out Story Root (max 1), Plot Arc, Act, Scene, and Comment nodes.
On the Character Canvas you can drag out Character nodes only.
</div>
<!-- ──────────────────────────────────────────────────────────────
2. NODE TYPES
────────────────────────────────────────────────────────────── -->
<h2 id="node-types">2. Node Types</h2>
<!-- ── Story Root ── -->
<h3 id="node-story-root">
<span class="node-chip chip-root"><span class="dot"></span> Story Root Node</span>
</h3>
<p>
The central anchor of a co-writing project. There is exactly <strong>one</strong> Story Root node
per project. It holds the high-level story metadata that defines the narrative's foundation:
title, genre, target audience, logline, characters, and synopsis. Plot nodes auto-connect to it.
</p>
<h4>StoryRootNodeData Fields</h4>
<dl class="fields">
<dt>title <code>string</code></dt>
<dd>The working title of the story. Can be changed at any time.</dd>
<dt>genre <code>string</code></dt>
<dd>Primary genre (e.g., Fantasy, Sci-Fi, Romance, Thriller, Horror, Mystery, Literary Fiction). Sets reader expectations for tone, pacing, and story conventions.</dd>
<dt>targetAudience <code>string</code></dt>
<dd>Who the story is written for (e.g., Young Adult, Adult, Middle Grade, New Adult). Affects language complexity, theme maturity, and content boundaries.</dd>
<dt>punchline <code>string</code></dt>
<dd>The "logline" or elevator pitch — capture the entire story in 1–2 sentences. Formula: <em>[Character] must [Goal] before [Stakes/Deadline], but [Obstacle].</em></dd>
<dt>mainCharacter <code>{ name: string, role: string }</code></dt>
<dd>The protagonist — the character whose journey drives the story. Should have a clear <em>want</em> (external goal) and a <em>need</em> (internal growth).</dd>
<dt>antagonist <code>{ name: string, role: string }</code></dt>
<dd>The primary opposing force. Can be a villain, rival, nature, society, or the protagonist's own flaws.</dd>
<dt>supportingCharacters <code>Array<{ name: string, archetype: string, customArchetype?: string }></code></dt>
<dd>Characters who help, hinder, or reflect the protagonist. Each should serve a narrative function and feel like a real person.</dd>
<dt>protagonistGoal <code>string</code></dt>
<dd>The one clear, concrete objective the protagonist pursues. This launches the plot (Act 1) and gets resolved at the climax (Act 3). Should be specific and measurable.</dd>
<dt>summary <code>string</code></dt>
<dd>A 300–500 word overview of the entire story from beginning to end, including the ending. Covers: hook, rising action, midpoint shift, crisis/climax, and resolution.</dd>
<dt>image <code>string?</code></dt>
<dd>Optional mood/concept image for the story. Can be AI-generated via the <code>generate_node_image</code> command.</dd>
</dl>
<h4>Visual Appearance</h4>
<p>
Rendered with a <strong>purple accent border</strong> and a crown/book icon. The title is displayed
prominently. If an image is set, it appears as a background or card header. Only one Story Root is
permitted per project.
</p>
<h4>How to Create</h4>
<p>
Drag the "Story Root" item from the toolbar on the Story Canvas. If one already exists, the toolbar
item is hidden. Programmatically, the root is created automatically when a co-write project is
initialized; use <code>update_story_root</code> to populate its fields.
</p>
<!-- ── Plot Node ── -->
<h3 id="node-plot">
<span class="node-chip chip-plot"><span class="dot"></span> Plot Node</span>
</h3>
<p>
Represents a narrative arc or storyline thread. Each plot node auto-connects to the Story Root
when created, establishing a parent-child relationship. A project can have any number of plots.
</p>
<h4>PlotNodeData Fields</h4>
<dl class="fields">
<dt>name <code>string</code></dt>
<dd>The plot's display name (e.g., "The Ring Quest", "Forbidden Love").</dd>
<dt>plotType <code>string</code></dt>
<dd>
One of: <code>Main Plot</code>, <code>Relationship Plot</code>, <code>Antagonist Plot</code>,
<code>Character Development Plot</code>, <code>Subplot</code>, <code>Custom</code>.
</dd>
<dt>customPlotType <code>string?</code></dt>
<dd>A free-text label used when <code>plotType</code> is "Custom" (e.g., "Political Intrigue Thread").</dd>
<dt>description <code>string</code></dt>
<dd>Description of the plot's arc — what it covers, how it escalates, how it resolves.</dd>
<dt>image <code>string?</code></dt>
<dd>Optional mood/concept image for the plot arc. AI-generatable.</dd>
</dl>
<h4>Plot Types Explained</h4>
<table>
<thead><tr><th>Type</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>Main Plot</code></td><td>The central storyline driven by the protagonist's primary goal. Every other plot connects to or contrasts with this one. Follows: Goal → Obstacles → Escalation → Crisis → Climax → Resolution.</td></tr>
<tr><td><code>Relationship Plot</code></td><td>A storyline about a key relationship (romantic, familial, or friendship). Provides the emotional core and runs parallel to the main plot.</td></tr>
<tr><td><code>Antagonist Plot</code></td><td>The storyline from the antagonist's perspective. Should escalate in parallel, creating increasing pressure on the protagonist.</td></tr>
<tr><td><code>Character Development Plot</code></td><td>An internal arc where a character overcomes a flaw, learns a truth, or transforms. The "need" vs "want" dynamic.</td></tr>
<tr><td><code>Subplot</code></td><td>A secondary storyline that enriches the world or themes. Good subplots echo the main plot's themes in a different key.</td></tr>
<tr><td><code>Custom</code></td><td>Any arc that doesn't fit standard categories: mystery threads, political intrigue, quests-within-quests, etc.</td></tr>
</tbody>
</table>
<h4>Visual Appearance</h4>
<p>
Rendered with an <strong>orange accent border</strong>. Displays the plot name and type badge.
Auto-connected to the Story Root via a directed edge upon creation.
</p>
<h4>How to Create</h4>
<p>
Drag from toolbar, or use the <code>create_plot</code> API command. The edge to the Story Root is
automatically created.
</p>
<!-- ── Act Node ── -->
<h3 id="node-act">
<span class="node-chip chip-act"><span class="dot"></span> Act Node</span>
</h3>
<p>
Represents a major structural division of the story (e.g., Act 1: Setup, Act 2: Confrontation,
Act 3: Resolution). Acts define the timeline and pacing structure. They can be connected to
Plot nodes via relationship edges to specify which parts of each plot play out in each act.
</p>
<h4>ActNodeData Fields</h4>
<dl class="fields">
<dt>actNumber <code>number</code></dt>
<dd>The act number (e.g., 1, 2, 3). Used for ordering and display.</dd>
<dt>name <code>string</code></dt>
<dd>Display name of the act (e.g., "The Setup", "Rising Action", "The Reckoning").</dd>
<dt>description <code>string</code></dt>
<dd>Description of what happens during this act — key events, turning points, character states.</dd>
<dt>image <code>string?</code></dt>
<dd>Optional mood/concept image for this act. AI-generatable.</dd>
</dl>
<h4>Three-Act Structure Reference</h4>
<table>
<thead><tr><th>Act</th><th>Proportion</th><th>Purpose</th></tr></thead>
<tbody>
<tr><td>Act 1 — Setup</td><td>~25%</td><td>Establish the ordinary world, introduce characters, present the inciting incident that disrupts the status quo.</td></tr>
<tr><td>Act 2 — Confrontation</td><td>~50%</td><td>Rising action, escalating conflicts, midpoint shift, complications, character growth under pressure.</td></tr>
<tr><td>Act 3 — Resolution</td><td>~25%</td><td>Crisis, climax, resolution. The protagonist faces the final challenge and the story's central question is answered.</td></tr>
</tbody>
</table>
<div class="infobox infobox-blue">
<strong>Tip:</strong> You can use more than three acts for finer-grained pacing. Each act should end
with a major turning point that propels the story forward.
</div>
<h4>Visual Appearance</h4>
<p>
Rendered with a <strong>teal accent border</strong>. Shows "Act N" with the act name and
description excerpt. Sorted by <code>actNumber</code> in the context listing.
</p>
<!-- ── Character Node ── -->
<h3 id="node-character">
<span class="node-chip chip-char"><span class="dot"></span> Character Node</span>
</h3>
<p>
A visual card on the Character Canvas that links to an entity in the project's entity system.
Character nodes allow you to map out relationships between characters using specialized
relationship edges. Changes sync bidirectionally with the entity system.
</p>
<h4>CharacterNodeData Fields</h4>
<dl class="fields">
<dt>entityId <code>string</code></dt>
<dd>The ID of the linked entity. The character node is a visual proxy — all actual data (name, description, profile, image) lives on the entity.</dd>
</dl>
<h4>Predefined Profile Fields</h4>
<p>The Character Node Inspector surfaces these predefined profile fields (stored on the entity's <code>profile</code> object):</p>
<table>
<thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>characterType</code></td><td>Dropdown</td><td>Narrative archetype: Protagonist, Antagonist, Sidekick, Mentor, Love Interest, Rival, Comic Relief, Guardian, Herald, Trickster, Shapeshifter, Threshold Guardian, Anti-hero, Foil, Custom</td></tr>
<tr><td><code>age</code></td><td>Text</td><td>Character's age or age range (e.g., "34", "Late twenties", "Ancient")</td></tr>
<tr><td><code>gender</code></td><td>Text</td><td>Gender identity, informing pronoun usage and social dynamics</td></tr>
<tr><td><code>appearance</code></td><td>Textarea</td><td>Physical description: height, build, hair, eyes, distinguishing features, typical clothing. Used by AI for image generation consistency</td></tr>
<tr><td><code>occupation</code></td><td>Text</td><td>Profession or role in the story world (e.g., "Blacksmith", "Court Spy", "Starship Engineer")</td></tr>
<tr><td><code>problemSolvingStrategies</code></td><td>Textarea</td><td>How the character approaches problems: fight, negotiate, trick, analyze, avoid? Defines their agency in scenes</td></tr>
</tbody>
</table>
<p>
Below the predefined fields, a <strong>ProfileViewer</strong> component allows adding arbitrary
free-form profile fields. Any key-value pair can be added (e.g., "motivations", "speech_style",
"inventory"). Profile values are inline-editable (click to edit).
</p>
<h4>Entity Features Available on Character Nodes</h4>
<ul>
<li><strong>Reference Image</strong> — A portrait that can be uploaded, AI-generated, or selected from project assets. Used by the image generator for visual consistency.</li>
<li><strong>Reference Voice</strong> — An audio clip for TTS voice matching. A 10–30 second clip with clear speech works best. Can be uploaded or AI-generated.</li>
</ul>
<!-- ── Scene Node ── -->
<h3 id="node-scene">
<span class="node-chip chip-scene"><span class="dot"></span> Scene Node</span>
</h3>
<p>
Scene nodes are still available on the Story Canvas in co-write mode. They work identically to
game mode: background image, story text, speaker name, choices, linked entities, and media
(background music, voiceover). Scenes allow you to draft actual content alongside the structural
planning.
</p>
<!-- ── Comment Node ── -->
<h3 id="node-comment">
<span class="node-chip chip-comment"><span class="dot"></span> Comment Node</span>
</h3>
<p>
Comments remain available on the Story Canvas for designer notes, TODO markers, and organizational
annotations. They do not affect gameplay or narrative structure. Each comment has a configurable
background color for visual categorization.
</p>
<!-- ──────────────────────────────────────────────────────────────
3. EDGE / RELATIONSHIP TYPES
────────────────────────────────────────────────────────────── -->
<h2 id="edge-types">3. Edge / Relationship Types</h2>
<!-- ── Char-to-Char ── -->
<h3 id="edge-char-char">Character-to-Character Relationships</h3>
<p>
When you draw an edge between two Character Nodes on the Character Canvas, it is created as a
<strong>relationship edge</strong> with a specialized data payload. These edges are rendered with
a <strong>dashed pink bezier curve</strong> and a label showing the relationship type.
</p>
<h4>RelationshipEdgeData Fields (Character-Character)</h4>
<dl class="fields">
<dt>relationshipType <code>string</code></dt>
<dd>The nature of the relationship (e.g., "Allies", "Rivals", "Romantic", "Mentor-Student", "Siblings", "Enemies").</dd>
<dt>description <code>string</code></dt>
<dd>Freeform description of the relationship's dynamics, power balance, and significance.</dd>
<dt>status <code>string</code></dt>
<dd>Current status of the relationship (e.g., "Strong", "Strained", "Broken", "Evolving").</dd>
<dt>history <code>string</code></dt>
<dd>Background history of how the relationship formed and key past events.</dd>
<dt>beginning <code>string?</code></dt>
<dd>How the relationship exists at the very start of the story. The baseline the audience measures all future changes against.</dd>
<dt>actDevelopments <code>Array<{ actLabel: string, development: string }>?</code></dt>
<dd>
Act-by-act tracking of how the relationship evolves. Each entry maps an act label to a description
of the relationship's shift during that act. Relationships should change — new information,
betrayals, shared ordeals, and revelations all reshape how characters feel about each other.
</dd>
<dt>ending <code>string?</code></dt>
<dd>How the relationship stands at the end of the story. Has it deepened, broken, reversed, or reached a new understanding? Should feel like a natural consequence of all preceding events.</dd>
<dt>entityId <code>string?</code></dt>
<dd>If a dedicated "relationship entity" was created in the entity system, its ID is stored here.</dd>
</dl>
<!-- ── Act-to-Plot ── -->
<h3 id="edge-act-plot">Act-to-Plot Connections</h3>
<p>
Relationship edges can also connect <strong>Act Nodes</strong> to <strong>Plot Nodes</strong>.
These edges use the <code>plotInvolvement</code> field to describe which parts of a plot arc
play out during a specific act.
</p>
<h4>RelationshipEdgeData Fields (Act-Plot)</h4>
<dl class="fields">
<dt>plotInvolvement <code>string?</code></dt>
<dd>
What parts of the plot play out in this act. For example: "Act 1 introduces the mystery and
plants the first clues" or "Act 2 deepens the romantic subplot with a betrayal revelation."
Mapping plots to acts helps visualize pacing — if all plot developments are crammed into
one act, the others may feel thin.
</dd>
</dl>
<div class="infobox infobox-yellow">
<strong>Pacing check:</strong> Connecting acts to plots creates a visual matrix of your story's pacing.
Every plot should have meaningful development in at least two acts. If one act has no plot connections,
consider whether it's carrying enough narrative weight.
</div>
<!-- ── Root-to-Plot ── -->
<h3 id="edge-root-plot">Story Root-to-Plot Links</h3>
<p>
When a Plot Node is created (via toolbar drag or API), an edge is <strong>automatically created</strong>
from the Story Root to the new plot node. These are standard directed edges (not relationship edges)
representing the parent-child hierarchy: the Story Root is the parent of all plot arcs.
</p>
<!-- ──────────────────────────────────────────────────────────────
4. CO-WRITING API COMMAND REFERENCE
────────────────────────────────────────────────────────────── -->
<h2 id="api-reference">4. Co-Writing API Command Reference</h2>
<p>
All commands use the Dream-E command block format. The AI chat agent emits these inline in its
responses, and they are executed sequentially by the agentic loop.
</p>
<pre><code><span class="kw"><<<SW_CMD:</span><span class="fn">command_name</span><span class="kw">>>></span>
{<span class="str">"param"</span>: <span class="str">"value"</span>, <span class="str">"anotherParam"</span>: <span class="num">42</span>}
<span class="kw"><<</SW_CMD>>></span></code></pre>
<p>
The <code>cowrite</code> group contains <strong>17 commands</strong> organized into six sub-groups.
All commands are available when the project is in co-write mode.
</p>
<!-- ─── Story Root Commands ─── -->
<h3 id="cmd-story-root">Story Root Commands</h3>
<details>
<summary><code>update_story_root</code> — Update story root fields</summary>
<div class="detail-body">
<p>Update any combination of story root fields. All parameters are optional — only the fields you include will be changed.</p>
<table>
<thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>title</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>Story title</td></tr>
<tr><td><code>genre</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>Genre (e.g. Fantasy, Sci-Fi, Romance)</td></tr>
<tr><td><code>targetAudience</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>Target audience (e.g. Young Adult, Adult)</td></tr>
<tr><td><code>punchline</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>One-line story hook / logline</td></tr>
<tr><td><code>protagonistGoal</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>What the protagonist wants to achieve</td></tr>
<tr><td><code>summary</code></td><td><code>string</code></td><td><span class="badge badge-optional">optional</span></td><td>Story summary / synopsis</td></tr>
<tr><td><code>mainCharacter</code></td><td><code>{name, role}</code></td><td><span class="badge badge-optional">optional</span></td><td>Main character object with name and role</td></tr>
<tr><td><code>antagonist</code></td><td><code>{name, role}</code></td><td><span class="badge badge-optional">optional</span></td><td>Antagonist object with name and role</td></tr>
<tr><td><code>supportingCharacters</code></td><td><code>[{name, archetype}]</code></td><td><span class="badge badge-optional">optional</span></td><td>Array of supporting characters with name and archetype</td></tr>
</tbody>
</table>
<p><strong>Returns:</strong> <code>{rootNodeId, updated}</code> — the story root node ID and a list of updated field names.</p>
<h4>Example</h4>
<pre><code><span class="kw"><<<SW_CMD:</span><span class="fn">update_story_root</span><span class="kw">>>></span>
{
<span class="str">"title"</span>: <span class="str">"The Last Cartographer"</span>,
<span class="str">"genre"</span>: <span class="str">"Fantasy"</span>,
<span class="str">"targetAudience"</span>: <span class="str">"Young Adult"</span>,
<span class="str">"punchline"</span>: <span class="str">"A blind mapmaker must chart a vanishing continent before it disappears forever, but every map she draws erases part of her memory."</span>,
<span class="str">"mainCharacter"</span>: {<span class="str">"name"</span>: <span class="str">"Sera Voss"</span>, <span class="str">"role"</span>: <span class="str">"protagonist"</span>},
<span class="str">"antagonist"</span>: {<span class="str">"name"</span>: <span class="str">"The Archivist"</span>, <span class="str">"role"</span>: <span class="str">"antagonist"</span>},
<span class="str">"protagonistGoal"</span>: <span class="str">"Map the Fading Isles before they vanish completely"</span>
}
<span class="kw"><<</SW_CMD>>></span></code></pre>
</div>
</details>
<details>
<summary><code>get_story_root</code> — Get all story root data</summary>
<div class="detail-body">
<p>Retrieves the complete story root document including all fields and the associated image.</p>
<table>
<thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
<tbody>
<tr><td colspan="4"><em>No parameters</em></td></tr>
</tbody>
</table>
<p><strong>Returns:</strong> <code>{rootNodeId, title, genre, targetAudience, punchline, mainCharacter, antagonist, supportingCharacters, protagonistGoal, summary, image}</code></p>
<h4>Example</h4>
<pre><code><span class="kw"><<<SW_CMD:</span><span class="fn">get_story_root</span><span class="kw">>>></span>
{}
<span class="kw"><<</SW_CMD>>></span></code></pre>
<div class="infobox infobox-blue">
<strong>Note:</strong> This is a read-only query command. Its full JSON response is sent back to the AI agent in the agentic loop, allowing the agent to reference the current story state before making changes.
</div>
</div>
</details>
<!-- ─── Plot Commands ─── -->