aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1// Resource: aesthetic-computer://kidlisp-reference
2// Comprehensive reference for KidLisp — the full 118-function API
3
4export const kidlispReferenceResource = {
5 uri: "aesthetic-computer://kidlisp-reference",
6 name: "KidLisp Language Reference",
7 description:
8 "Complete reference for KidLisp: a creative coding Lisp dialect with 118 functions across 12 categories for generative art on aesthetic.computer",
9 mimeType: "text/markdown",
10};
11
12export function getKidLispReference() {
13 return `# KidLisp Language Reference
14
15KidLisp is a minimal Lisp dialect for creating generative art and interactive experiences on aesthetic.computer.
16It uses S-expressions where the first element is a function name followed by arguments.
17
18## Syntax Basics
19
20\`\`\`lisp
21; Comments start with semicolon
22(function-name arg1 arg2 ...)
23
24; Shorthand comma syntax (no parens needed for simple commands)
25purple, ink, line, blur 5
26
27; Variables
28(def name value)
29(def x 10)
30
31; Functions
32(later name param1 param2 body...)
33(later star x y (ink "yellow") (circle x y 20))
34(star 100 100)
35
36; Conditionals
37(if condition then else)
38
39; Loops
40(repeat count expression...)
41(repeat count iterator expression...)
42(bunch 50 (plot (wiggle width) (wiggle height))) ; bunch = alias for repeat
43\`\`\`
44
45**Identifier rules:** Must start with letter or underscore. Can contain letters, digits, underscores. **No dashes** (parsed as subtraction). Use \`my_var\` not \`my-var\`.
46
47**String literals:** Both \`"text"\` and \`'text'\` work.
48
49**Shorthand:** \`w\` = width, \`h\` = height, \`f\` = frame. \`?\` = random, \`...\` = cycle through values.
50
51## Screen Management
52
53| Function | Usage | Description |
54|----------|-------|-------------|
55| \`wipe\` | \`(wipe color)\` | Clear screen with color |
56| \`resolution\` | \`(resolution w h)\` | Set canvas resolution |
57| \`coat\` | \`(coat color alpha)\` | Semi-transparent overlay |
58| \`mask\` | \`(mask x y w h)\` | Restrict drawing to region |
59| \`unmask\` | \`(unmask)\` | Remove drawing mask |
60
61## Drawing Primitives
62
63| Function | Usage | Description |
64|----------|-------|-------------|
65| \`ink\` | \`(ink color)\` or \`(ink r g b)\` or \`(ink color alpha)\` | Set drawing color |
66| \`line\` | \`(line x1 y1 x2 y2)\` or \`(line)\` for random | Draw line between two points |
67| \`lines\` | \`(lines points...)\` | Draw connected lines |
68| \`box\` | \`(box x y w h)\` | Draw rectangle (respects fill/outline mode) |
69| \`circle\` | \`(circle x y radius)\` | Draw circle (respects fill/outline mode) |
70| \`tri\` | \`(tri x1 y1 x2 y2 x3 y3)\` | Draw triangle |
71| \`plot\` / \`point\` | \`(plot x y)\` | Set single pixel |
72| \`flood\` | \`(flood x y)\` | Flood fill area |
73| \`shape\` | \`(shape points... "fill")\` | Draw polygon |
74
75Shapes accept explicit mode overrides: \`(circle x y r "fill")\`, \`(circle x y r "outline")\`, \`(circle x y r "outline:5")\`
76
77## Fill/Outline Modes
78
79| Function | Description |
80|----------|-------------|
81| \`(fill)\` | Set global fill mode (default) |
82| \`(outline)\` | Set global outline mode |
83| \`(stroke)\` | Alias for outline |
84| \`(nofill)\` | Alias for outline |
85| \`(nostroke)\` | Alias for fill |
86
87## Color System
88
89Colors can be specified as:
90- **Named:** \`"red"\`, \`"blue"\`, \`"lime"\`, \`"navy"\`, \`"coral"\`, etc. (all CSS color names)
91- **Bare words:** \`red\`, \`blue\`, \`purple\` (no quotes needed)
92- **RGB:** \`(ink 255 0 0)\`
93- **With alpha:** \`(ink "red" 128)\` or \`(ink red 128)\` (0-255, where 255 is opaque)
94- **Special:** \`rainbow\` (cycling colors), \`zebra\` (black/white alternating), \`erase\` (transparent)
95- **Fade gradients:** \`fade:red-blue-black\`, \`fade:zebra-rainbow-zebra\`, \`fade:color1-color2:direction\`
96
97## Math & Numbers
98
99| Function | Usage | Description |
100|----------|-------|-------------|
101| \`+\` | \`(+ a b c...)\` | Addition |
102| \`-\` | \`(- a b)\` | Subtraction |
103| \`*\` | \`(* a b c...)\` | Multiplication |
104| \`/\` | \`(/ a b)\` | Division. Also works as inline: \`width/2\`, \`h/2\` |
105| \`%\` / \`mod\` | \`(% a b)\` | Modulo |
106| \`sin\` | \`(sin x)\` | Sine |
107| \`cos\` | \`(cos x)\` | Cosine |
108| \`random\` / \`?\` | \`(random max)\` or \`(? a b c)\` | Random number or random choice |
109| \`wiggle\` | \`(wiggle amount)\` | Random ±amount/2 |
110| \`min\` | \`(min a b c...)\` | Minimum value |
111| \`max\` | \`(max a b c...)\` | Maximum value |
112| \`abs\` | \`(abs x)\` | Absolute value |
113| \`sqrt\` | \`(sqrt x)\` | Square root |
114| \`pow\` | \`(pow base exp)\` | Power |
115| \`floor\` | \`(floor x)\` | Floor |
116| \`ceil\` | \`(ceil x)\` | Ceiling |
117| \`round\` | \`(round x)\` | Round |
118
119## System Properties
120
121| Name | Description |
122|------|-------------|
123| \`width\` / \`w\` | Canvas width |
124| \`height\` / \`h\` | Canvas height |
125| \`frame\` / \`f\` | Current frame number |
126| \`clock\` | UTC timestamp |
127| \`pi\` | Math constant |
128
129## Control Flow & Variables
130
131| Function | Usage | Description |
132|----------|-------|-------------|
133| \`def\` | \`(def name value)\` | Define variable |
134| \`later\` | \`(later name params body...)\` | Define function |
135| \`if\` | \`(if cond then else)\` | Conditional |
136| \`once\` | \`(once expr)\` | Execute only once per session |
137| \`now\` | \`(now var value)\` | Update variable immediately |
138| \`not\` | \`(not expr)\` | Logical negation |
139| \`die\` | \`(die)\` | Stop execution |
140| \`repeat\` / \`rep\` / \`bunch\` | \`(repeat count iter expr...)\` | Loop with optional iterator |
141| \`choose\` / \`?\` | \`(? a b c)\` | Random selection from options |
142| \`...\` | \`(... a b c)\` | Cycle through values over time |
143
144## Animation & Timing
145
146Timing expressions control when code runs:
147- \`1s\` — Execute after 1 second
148- \`2s...\` — Cycle through values every 2 seconds (repeating)
149- \`0.5s!\` — Execute once after 0.5 seconds
150- \`0.1s\` — Execute every 0.1 seconds (fast timer)
151
152\`\`\`lisp
153(once (wipe "black"))
1541s (ink "red") (circle 100 100 50)
1552s (ink "blue") (box 150 150 40 40)
156(0.25s (wipe (... red yellow blue))) ; Cycle background color
157(0.1s (ink (? black white) 32) (circle ? ? 32)) ; Random circles periodically
158\`\`\`
159
160## Pixel Transformations (11 functions)
161
162| Function | Usage | Description |
163|----------|-------|-------------|
164| \`scroll\` | \`(scroll dx dy)\` or \`(scroll dx)\` | Translate pixels with wrapping |
165| \`zoom\` | \`(zoom factor)\` | Scale from center (>1 zoom in, <1 zoom out) |
166| \`spin\` | \`(spin angle)\` | Rotate canvas (degrees) |
167| \`suck\` | \`(suck strength [cx cy])\` | Radial vortex displacement |
168| \`blur\` | \`(blur amount)\` | Gaussian blur |
169| \`contrast\` | \`(contrast amount)\` | Adjust contrast (>1 increase, <1 decrease) |
170| \`sort\` | \`(sort)\` | Sort pixels by brightness |
171| \`pan\` | \`(pan dx dy)\` | Pan camera view |
172| \`unpan\` | \`(unpan)\` | Reset camera position |
173| \`resetSpin\` | \`(resetSpin)\` | Reset rotation |
174| \`smoothspin\` | \`(smoothspin angle)\` | Smooth rotation |
175| \`bake\` | \`(bake)\` | Commit current drawing to background layer |
176
177## Images & Media
178
179| Function | Usage | Description |
180|----------|-------|-------------|
181| \`paste\` | \`(paste url x y [scale])\` | Paste image at position (URLs can be unquoted) |
182| \`stamp\` | \`(stamp url x y [scale])\` | Paste image centered |
183| \`painting\` | \`(painting x y)\` | Paste current user's painting |
184| \`steal\` | \`(steal)\` | Copy current buffer |
185| \`putback\` | \`(putback)\` | Restore copied buffer |
186| \`tape\` | \`(tape !CODE x y w h [speed])\` | Embed a tape video |
187
188### Text
189
190| Function | Usage | Description |
191|----------|-------|-------------|
192| \`write\` | \`(write text x y [bg] [size])\` | Draw text |
193| \`len\` | \`(len text)\` | Get text length |
194
195## Audio & Sound
196
197| Function | Usage | Description |
198|----------|-------|-------------|
199| \`mic\` | \`(mic)\` | Access microphone |
200| \`amplitude\` | \`(amplitude)\` | Get audio amplitude |
201| \`speaker\` | \`(speaker)\` | Audio output control |
202| \`melody\` | \`(melody notes)\` | Play musical sequence |
203| \`overtone\` | \`(overtone freq)\` | Generate harmonic tones |
204| \`noise\` | \`(noise)\` | Generate white noise |
205
206## 3D Graphics
207
208| Function | Usage | Description |
209|----------|-------|-------------|
210| \`cube\` | \`(cube id)\` | Create/reference 3D cube |
211| \`quad\` | \`(quad)\` | Create quad primitive |
212| \`form\` | \`(form objects...)\` | Render 3D forms |
213| \`trans\` | \`(trans form transforms...)\` | Transform 3D objects (move, scale, spin) |
214| \`cubespin\` | \`(cubespin x y z)\` | Animate cube rotation |
215| \`cubepos\` | \`(cubepos x y z)\` | Set cube position |
216| \`cubescale\` | \`(cubescale factor)\` | Scale cube |
217| \`camrot\` / \`camspin\` | \`(camrot x y z)\` | Camera rotation / animation |
218
219## Embedding & Navigation
220
221| Function | Usage | Description |
222|----------|-------|-------------|
223| \`embed\` | \`(embed $codeId x y w h alpha)\` | Embed another piece with position/size |
224| \`$codeId\` | \`($codeId)\` or \`($codeId x y w h alpha)\` | Execute/embed cached code by ID |
225| \`jump\` | \`(jump "piece")\` or \`(jump $id)\` | Navigate to another piece |
226| \`hop\` | \`(hop url)\` | Navigate to URL |
227
228## Utility
229
230| Function | Usage | Description |
231|----------|-------|-------------|
232| \`tap\` | \`(tap expr)\` | Handle touch/click events |
233| \`draw\` | \`(draw)\` | Force redraw |
234| \`label\` | \`(label text color offset)\` | HUD label overlay |
235| \`fps\` | \`(fps rate)\` | Set frame rate |
236| \`debug\` | \`(debug value)\` | Debug logging |
237| \`yes\` / \`no\` | Boolean true / false |
238
239## Best Practices
240
2411. **Start with a background** — \`(wipe color)\` or just a bare color name like \`black\`
2422. **Set \`(ink color)\` before drawing** — all primitives use the current ink
2433. **Use \`?\` for randomness** — \`(? red blue green)\` picks randomly
2444. **Use \`...\` for cycling** — \`(... red blue green)\` cycles over time
2455. **Use \`wiggle\` for organic movement** — \`(circle (wiggle w) (wiggle h) 10)\`
2466. **Combine transforms for feedback loops** — scroll + zoom + blur creates trails
2477. **Use \`once\` for setup** — \`(once (wipe "black"))\` runs only on first frame
2488. **Use \`bake\` for layering** — commits drawing to background
2499. **Timing expressions drive animation** — \`0.1s\`, \`1s...\`, etc.
25010. **Bare words work** — \`red\` = \`(wipe "red")\`, \`line\` = \`(line)\` with random coords
251
252Live reference with function popularity data: https://kidlisp.com/learn
253`;
254}