/ README.md
README.md
1 # DreamTalk 2  3  4 5 ## Philosophical Meaning 6 7 DreamTalk represents the extension of the ancient indigenous modality of SandTalk, popularised through [Tyson Yunkapurta's book](https://www.amazon.com/Sand-Talk-Indigenous-Thinking-World/dp/0062975641), into the digital domain. 8 9 SandTalk's constraints (symbols must be drawable in sand during campfire conversation): 10 - Line based 11 - Two dimensional 12 - No colouring, shading, or movement 13 14 DreamTalk expands these principles while retaining their essence: 15 - Line based (SVGs, splines) 16 - Two and three dimensional 17 - Basic colouring and shading 18 - Animations allowed 19 20 Photorealistic images or painterly styles (Van Gogh) are outside this class. 21 22 ## Technical Implementation 23 24 A Python-based programmatic animation library inspired by 3blue1brown's manim, using Cinema 4D as its backend. 25 26 ## MCP Integration 27 28 DreamTalk includes a Cinema 4D MCP server enabling Claude to interact directly with C4D via socket-based communication. This enables prompt-driven DreamTalk symbol creation and iteration. 29 30 See `CLAUDE.md` for the complete AI workflow. 31 32 --- 33 34 ## Future Vision 35 36 ### Backend Abstraction 37 38 DreamTalk's Python API can target multiple render backends: 39 40 ``` 41 DreamTalk Python API 42 │ 43 ├── Cinema 4D Backend (current) 44 │ └── Professional: MoGraph, particles, procedural tools 45 │ 46 └── WebGL Backend (future) 47 └── Real-time: browser-native, interactive, InterBrain UI 48 ``` 49 50 ### WebGL Feasibility 51 52 **Straightforward to port:** 53 - Primitives, splines, materials 54 - Animation/keyframe system 55 - Cloner, Fields, Effectors (math-based) 56 - Vertex maps, infection/growth (GPU shaders) 57 - Particle systems, basic physics 58 59 **Challenging:** 60 - 3D silhouette → vector spline extraction 61 - Spline morphing with topology mismatch 62 - Complex deformers 63 64 **C4D remains valuable for:** 65 - MoGraph advanced features 66 - Sketch & Toon outline-to-spline 67 - Complex procedural workflows 68 - Professional master renders 69 70 ### Prompt-to-Symbol Pipeline 71 72 The ultimate vision: 73 ``` 74 Natural language prompt 75 ↓ (AI) 76 DreamTalk Python code 77 ↓ (WebGL or C4D backend) 78 Rendered symbol (MP4/real-time) 79 ``` 80 81 WebGL enables this fully browser-native. C4D requires hosted service. 82 83 --- 84 85 ## Known Limitations & Challenges 86 87 ### Easing Cascade Problem 88 89 When nested CustomObjects each define `specify_creation()` with easing, the easings compound through the holarchy, producing non-visually-appealing effects. 90 91 **Current workaround:** Manually coordinate creation animations at the top level, or use linear interpolation for child objects. 92 93 **Future solution needed:** Easing applied only at outermost level, children receive "raw" normalized time. 94 95 ### Animation State Management 96 97 **Status: Partially Solved** 98 99 State machines are now implemented in the syntax (`class States` with `State()` definitions). Holons like MindVirus declare states with target parameter values and can transition between them. 100 101 **Remaining work:** Automatic entry/exit animations per state, state change propagation through holarchy. 102 103 ### Physics vs Keyframe Animation 104 105 **Status: Active Development** 106 107 The MindVirus holon now implements physics-based jellyfish locomotion with thrust, drag, and momentum. The `simulate()` method runs physics frame-by-frame and bakes to keyframes. 108 109 **Next phase:** Full agentic animation system with steering behaviors. See [docs/VISION_AGENTIC_ANIMATION.md](docs/VISION_AGENTIC_ANIMATION.md). 110 111 ### Holarchic Animation Inheritance 112 113 When a symbol is used in a higher holon, the parent may need to trigger child animations, override parameters, or add new behaviors the child didn't anticipate. 114 115 The "software gardening" philosophy suggests: implement in the higher holon first, then extract reusable parts back to the child only if they prove generally useful. 116 117 ### MoGraph vs Agentic Animation 118 119 **Status: Architecture Clarified** 120 121 MoGraph clones are stateless - they cannot move themselves or remember state between frames. For true agentic behavior (self-directed movement, neighbor awareness, goal pursuit), we use Python simulation with MoGraph optionally handling rendering at scale. 122 123 See [docs/VISION_AGENTIC_ANIMATION.md](docs/VISION_AGENTIC_ANIMATION.md) for the complete architecture. 124 125 --- 126 127 ## Future Vision: Agentic Animation 128 129 Beyond keyframe animation, DreamTalk is evolving toward **digital spirits** - holons with agency that understand verbs like `emerge_from()`, `wander()`, `find_place_in()`, and manifest appropriate behavior. 130 131 **Core concepts:** 132 - **Verb System**: Behaviors as vocabulary the holon understands 133 - **Holonic Agency**: Agency at every level of the holarchy 134 - **Steering Behaviors**: Proven algorithms (seek, arrive, separation, cohesion) 135 - **Formations**: Self-organization into structures 136 - **Emergent Cable Physics**: Organic motion as consequence of movement 137 138 **Target scenes:** 139 - Invisible Hand: 5 MindViruses with puppet-string cables swarm toward target 140 - Double Wall: 100+ MindViruses self-assemble into labyrinth structure 141 142 See [docs/VISION_AGENTIC_ANIMATION.md](docs/VISION_AGENTIC_ANIMATION.md) for the complete vision and roadmap.