aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# KidLisp
2
3KidLisp is a minimal Lisp dialect designed for creating generative art and interactive experiences within the Aesthetic Computer system. It provides a simple yet powerful language for expressing visual and temporal patterns.
4
5## 🗂️ Directory Structure
6
7### Core Implementation
8- **`system/public/aesthetic.computer/lib/kidlisp.mjs`** - The main KidLisp evaluator and runtime
9- **`system/netlify/functions/store-kidlisp.mjs`** - Backend storage and retrieval API for KidLisp pieces
10
11### Tools
12- **`kidlisp/tools/`** - Development and analysis tools
13 - `source-tree.mjs` - Analyzes embedded layer structure and performance characteristics
14 - `get-source.mjs` - Simple source code fetcher
15 - `README.md` - Tool documentation
16
17### Documentation
18- **`docs/kidlisp-embed-feature.md`** - Embedding system documentation
19- **`docs/kidlisp-feed-feature.md`** - Feed system documentation
20- **`reports/tape-command-research.md`** - Analysis of tape recording system and framerate issues
21
22### Examples & Tests
23- **`kidlisp/examples/`** - Example KidLisp pieces and patterns
24- **`kidlisp/tests/`** - Test suite for the evaluator
25
26## 🚀 Quick Start
27
28### Running KidLisp
29KidLisp pieces are executed within the Aesthetic Computer environment. The main entry point is through the `kidlisp.mjs` evaluator.
30
31### Analyzing Pieces
32Use the tools in `kidlisp/tools/` to analyze existing pieces:
33
34```bash
35# Analyze structure and performance
36./kidlisp/tools/source-tree.mjs $cow
37
38# Get raw source code
39./kidlisp/tools/get-source.mjs $ican
40```
41
42Both tools require the dev server to be running (`npm run dev`) as they connect to the local KidLisp storage API.
43
44## 📖 Language Reference
45
46### Basic Syntax
47KidLisp uses S-expressions (parentheses-based syntax):
48```lisp
49(function arg1 arg2 ...)
50```
51
52### Core Functions
53The evaluator in `kidlisp.mjs` implements a comprehensive set of **118 functions** across 12 categories:
54
55- **Graphics**: `wipe`, `ink`, `line`, `box`, `circle`, `tri`, `plot`, `flood`, `shape`
56- **Transformations**: `zoom`, `scroll`, `spin`, `blur`, `contrast` - 11 pixel-level effects
57- **Math**: `+`, `-`, `*`, `/`, `sin`, `cos`, `random`, `wiggle` - 14 mathematical operations
58- **3D Graphics**: `cube`, `form`, `trans` - 8 three-dimensional functions
59- **Audio**: `mic`, `melody`, `overtone` - 6 sound processing functions
60- **System**: `width`, `height`, `frame`, `clock`, `fps` - 9 system properties
61- **Colors**: All CSS colors plus `rainbow`, `zebra` - 19 color functions
62- **Control**: `def`, `later`, `if`, `once`, `repeat` - 7 language constructs
63
64#### Graphics & Transformations
65KidLisp provides 11 pixel-level transformation functions:
66
67- **`(scroll x y)`** - Translation with wrapping
68- **`(zoom factor)`** - Scale transformation with accumulation
69- **`(spin angle)`** - Rotation around screen center
70- **`(blur amount)`** - Gaussian blur effect
71- **`(contrast level)`** - Contrast adjustment
72- **`(blur amount)`** - Gaussian blur effect
73
74Examples:
75```lisp
76(scroll 5 0) ; Move right by 5 pixels
77(zoom 1.1) ; Gradual zoom in
78(spin 1) ; Slow rotation
79(blur 2) ; Soft blur effect
80```
81
82*For a complete API reference with all 118 functions, see [`COMPLETE_API_MAP.md`](COMPLETE_API_MAP.md).*
83
84*For detailed transformation documentation, see [`docs/suck-complete-technical-guide.md`](docs/suck-complete-technical-guide.md).*
85
86## 🔧 Architecture
87
88### Evaluator (`kidlisp.mjs`)
89The main evaluator is a tree-walking interpreter that:
90- Parses S-expressions into an AST
91- Maintains execution context and variable bindings
92- Provides built-in functions for graphics and interaction
93- Handles embedded piece loading and execution
94- Manages performance optimization for real-time rendering
95
96### Storage Backend (`store-kidlisp.mjs`)
97The storage system provides:
98- **POST** - Store new KidLisp pieces
99- **GET `?code=nanoid`** - Retrieve single piece by ID
100- **GET `?codes=id1,id2,id3`** - Batch retrieve multiple pieces
101- Persistent storage with nanoid-based addressing
102
103### Embedding System
104KidLisp supports embedding other pieces as layers:
105```lisp
106($other-piece-id arg1 arg2)
107```
108This enables composition and reusability while maintaining performance through caching.
109
110## 🔄 Transformation Functions
111
112KidLisp includes 11 transformation functions for pixel manipulation:
113
114| Function | Purpose | Example |
115|----------|---------|---------|
116| `scroll` | Move pixels with wrapping | `(scroll 5 0)` |
117| `zoom` | Scale from center | `(zoom 1.1)` |
118| `spin` | Rotate canvas | `(spin 1)` |
119| `blur` | Gaussian blur | `(blur 2)` |
120| `contrast` | Adjust contrast | `(contrast 1.5)` |
121| `suck` | Radial displacement | `(suck 0.5)` |
122| `pan` | Camera movement | `(pan 10 5)` |
123| `sort` | Sort pixels by brightness | `(sort)` |
124| `resetSpin` | Reset rotation | `(resetSpin)` |
125| `smoothspin` | Smooth rotation | `(smoothspin 0.1)` |
126| `unpan` | Reset camera | `(unpan)` |
127
128```lisp
129; Basic transformation examples
130(scroll 5 0) ; Move right by 5 pixels
131(zoom 1.1) ; Gradual zoom in
132(spin 1) ; Slow rotation
133(blur 2) ; Soft blur effect
134(suck 0.5) ; Radial displacement
135```
136
137## 🛠️ Development
138
139### Tools
140The `kidlisp/tools/` directory contains utilities for:
141- **Source Analysis** - Understanding piece structure and dependencies
142- **Performance Profiling** - Identifying expensive operations
143- **Debugging** - Inspecting piece execution
144
145### Testing
146Run the test suite to validate evaluator behavior:
147```bash
148# TODO: Add test runner instructions
149```
150
151### Contributing
152When modifying the evaluator:
1531. Test with existing pieces to ensure compatibility
1542. Update this documentation for new features
1553. Add examples for new language constructs
1564. For new transformation functions, follow the established patterns:
157 - Add to `graph.mjs` with mask support and wrapping behavior
158 - Add to `kidlisp.mjs` with deferred execution support
159 - Include in embedded layer special function lists
160 - Test with both immediate and deferred execution contexts
161
162**Recent Additions (2025-09-06):**
163- Complete documentation organization with 118-function API map
164- Development tools for API analysis and function discovery
165
166## 🚀 Summary
167
168KidLisp is a comprehensive creative coding language with **118 functions** designed for real-time visual art. Key strengths include:
169
170- **Rich API**: 12 function categories covering graphics, math, 3D, audio, and system control
171- **Live coding**: Interactive development with immediate visual feedback
172- **Advanced transformations**: 11 pixel-level effects for visual manipulation
173- **Embedded systems**: Code composition and layer management
174- **Performance**: Optimized evaluation with caching and deferred execution
175
176### Quick Start
177```lisp
178(wipe "navy") ; Set background
179(ink "yellow") ; Set drawing color
180(repeat 50 i ; Draw 50 circles
181 (circle (wiggle width) (wiggle height) 10))
182```
183
184### Resources
185- **[Complete API Map](COMPLETE_API_MAP.md)** - All 118 functions categorized
186- **[Function Drilldowns](docs/functions/)** - Detailed guides for specific functions
187- **[Development Tools](tools/)** - Analysis and debugging utilities
188- **[Technical Reports](reports/)** - Implementation research and comparisons
189
190## 📚 Related Documentation
191
192- [Embedding System](docs/features/embedding-system.md)
193- [Feed System](docs/features/feed-system.md)
194- [Architecture Analysis Reports](reports/) - Technical deep-dives and comparisons
195
196## 🎯 Philosophy
197
198KidLisp embodies the aesthetic computer philosophy of simplicity and expressiveness. It provides just enough power to create compelling visual experiences while remaining approachable for beginners and powerful for experts.
199
200The language is designed to feel immediate and responsive, with changes reflected in real-time. This makes it ideal for live coding, artistic exploration, and interactive installations.
201
202*KidLisp: Expressive creative coding for the Aesthetic Computer platform.*