aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# KidLisp Language Reference
2
3*Documentation for the KidLisp programming language in Aesthetic Computer*
4
5## Overview
6
7KidLisp is a Lisp-based visual programming language designed for creating interactive art and animations in Aesthetic Computer. It provides a simple, expressive syntax for graphics, animation, and user interaction.
8
9## Basic Syntax
10
11### S-Expressions
12KidLisp uses S-expressions (parenthesized lists) where the first element is a function name followed by arguments:
13
14```lisp
15(function-name arg1 arg2 arg3)
16```
17
18### Comments
19```lisp
20; This is a comment
21; Comments start with semicolon and go to end of line
22```
23
24### Multi-line Expressions
25Expressions can span multiple lines for readability:
26```lisp
27(box 10 20
28 100 150
29 "outline")
30```
31
32## Core Language Features
33
34### Variables
35Define variables with `def`:
36```lisp
37(def x 10)
38(def color "red")
39(def size 50)
40```
41
42**Important**: Variable names cannot contain dashes/hyphens (-) as they are parsed as subtraction:
43- ✅ Valid: `myVar`, `line_width`, `color2`
44- ❌ Invalid: `my-var`, `line-width` (parsed as subtraction)
45
46### Functions
47Define reusable functions with `later`:
48```lisp
49(later square x y size
50 (box x y size size))
51
52; Call the function
53(square 50 50 100)
54```
55
56### Math Operations
57```lisp
58(+ 5 3 2) ; Addition: 10
59(- 10 3) ; Subtraction: 7
60(* 4 5 2) ; Multiplication: 40
61(/ 20 4) ; Division: 5
62```
63
64## Graphics Functions
65
66### Screen Management
67```lisp
68(wipe "black") ; Clear screen with color
69(wipe 255 0 0) ; Clear with RGB red
70(resolution 800 600) ; Set canvas size
71```
72
73### Drawing Colors
74```lisp
75(ink "red") ; Set color by name
76(ink 255 0 0) ; Set RGB color
77(ink "blue" 128) ; Set color with transparency
78(ink 100 200 255 180) ; RGBA color
79```
80
81### Drawing Primitives
82```lisp
83(line 10 10 90 90) ; Draw line
84(box 50 50 100 75) ; Draw rectangle
85(circle 100 100 50) ; Draw circle
86(tri 50 10 10 90 90 90) ; Draw triangle
87(tri 50 10 10 90 90 90 "outline") ; Triangle outline
88(plot 100 200) ; Set single pixel
89```
90
91### Images
92```lisp
93(paste "https://example.com/image.png" 0 0) ; Paste image at position
94(paste @user/123456 50 50) ; Paste from user timestamp
95(stamp "image.png" 100 100) ; Paste centered at position
96(paste "image.png" 0 0 0.5) ; Paste with 50% scale
97```
98
99## Animation & Timing
100
101### Timing Expressions
102```lisp
1031s ; Execute after 1 second
1042s... ; Execute every 2 seconds (repeating)
1050.5s! ; Execute once after 0.5 seconds
106```
107
108### Dynamic Values
109```lisp
110(wiggle 10) ; Random variation (±5)
111width ; Canvas width
112height ; Canvas height
113```
114
115### Animation Example
116```lisp
117(def x 0)
118
119; Move box across screen
120(def x (+ x 1))
121(box x 100 50 50)
122
123; Reset when reaching edge
124(def x (% x width))
125```
126
127## Color System
128
129### Named Colors
130```lisp
131"red" "blue" "green" "yellow" "orange" "purple"
132"pink" "cyan" "magenta" "lime" "brown" "gray"
133"black" "white"
134```
135
136### RGB Values
137```lisp
138(ink 255 0 0) ; Pure red
139(ink 0 255 0) ; Pure green
140(ink 0 0 255) ; Pure blue
141(ink 128 128 128) ; Gray
142```
143
144### Transparency
145```lisp
146(ink "red" 128) ; 50% transparent red
147(ink 255 0 0 128) ; 50% transparent red (RGBA)
148```
149
150## Advanced Features
151
152### Control Flow
153```lisp
154; Conditional logic (basic comparison)
155(def size (+ 50 (wiggle 20)))
156```
157
158### Loops and Repetition
159```lisp
160; Repeating patterns using timing
1612s... (circle (wiggle width) (wiggle height) 20)
162```
163
164### Complex Compositions
165```lisp
166(later flower x y
167 (circle x y 20)
168 (circle (- x 15) (- y 10) 8)
169 (circle (+ x 15) (- y 10) 8)
170 (circle x (+ y 15) 12))
171
172; Draw multiple flowers
173(flower 100 100)
174(flower 200 150)
175(flower 300 200)
176```
177
178## Built-in Constants
179
180### Screen Dimensions
181- `width` - Canvas width in pixels
182- `height` - Canvas height in pixels
183
184### Math Constants
185Access to JavaScript Math constants and functions.
186
187## Examples
188
189### Simple Animation
190```lisp
191(wipe "black")
192(ink "cyan")
193(def time (* frame 0.1))
194(circle (+ 100 (* 50 (sin time)))
195 (+ 100 (* 30 (cos time)))
196 20)
197```
198
199### Interactive Drawing
200```lisp
201(wipe "navy")
202(ink "yellow")
203; Draw circles that follow mouse/touch
204(circle mouseX mouseY 25)
205```
206
207### Geometric Pattern
208```lisp
209(wipe "black")
210(ink "lime")
211
212(later spiral angle radius
213 (def x (+ (/ width 2) (* radius (cos angle))))
214 (def y (+ (/ height 2) (* radius (sin angle))))
215 (circle x y 5))
216
217; Draw spiral pattern
218(def angle 0)
219(def angle (+ angle 0.2))
220(spiral angle (* angle 2))
221```
222
223## Integration with JavaScript API
224
225KidLisp programs run on top of the Aesthetic Computer JavaScript API. Functions like `wipe`, `ink`, `box`, etc. are provided by the underlying `disk.mjs` system.
226
227## Language Status
228
229**✅ Core Features Implemented**
230- S-expression parsing and evaluation
231- Variable definition and scoping
232- Function definition with `later`
233- Graphics primitives
234- Math operations
235- Timing expressions
236- Image loading and display
237
238**🚧 In Development**
239- Advanced control flow
240- List manipulation
241- More built-in functions
242- Error handling improvements
243- Debugging tools
244
245---
246
247*This reference is extracted from the comprehensive LLM API specification embedded in kidlisp.mjs and represents the current state of the language.*