squeak/squot code base for Alan Kay's Croquet on 64 bit Squeak Smalltalk.
# Croquet64SDK
*A port of Alan Kay's Croquet collaborative virtual world to 64-bit Squeak Smalltalk.*
---
## Vision
Croquet was one of the most ambitious projects in the history of Smalltalk and perhaps in
the history of computing. A fully collaborative, peer-to-peer 3D virtual world, built
entirely in Smalltalk, with a distributed object model (TeaTime) that kept every
participant's world in perfect sync — with no central server.
The original team got it running. But the documentation was never comprehensive, and the
codebase was left behind as Squeak moved forward. This project exists to change that.
**Croquet64SDK** is a collaborative effort to:
- Understand the original Croquet architecture by reading and documenting its source
- Get Croquet running reliably on modern 64-bit Squeak (6.x)
- Build it forward from that foundation
This is not a museum project. The goal is a living, working system.
---
## Project Structure
```
Croquet64SDK/
├── README.md ← You are here
├── docs/
│ ├── architecture/ ← High-level system diagrams (.dia files)
│ ├── subsystems/ ← One directory per subsystem (see below)
│ ├── setup/ ← Platform-specific setup guides
│ └── original/ ← Original Croquet documentation, preserved as-is
├── images/
│ ├── 32bit/ ← Squeak 4.x images (known-working reference)
│ │ └── updatedKrestiavano-1.0.25/
│ └── 64bit/ ← Squeak 6.x images (work in progress)
├── src/
│ ├── 32bit/
│ │ ├── monticello/ ← .mcz packages exported from Squeak 4.x
│ │ └── fileouts/ ← .st fileouts as plain-text fallback
│ └── 64bit/
│ ├── tonel/ ← Modern Tonel format for Squeak 6.x
│ └── gitfiletree/ ← GitFileTree format (alternative)
└── tools/
└── scripts/
├── 32bit/ ← Launch scripts for 32-bit Squeak
└── 64bit/ ← Launch scripts for 64-bit Squeak
```
---
## The 18 Subsystems
The Croquet architecture is organized into 18 subsystems. Each has its own directory
under `docs/subsystems/` where documentation, diagrams, notes, and source analysis live.
| # | Subsystem | Status |
|---|-----------|--------|
| 01 | Islands & Replication | 🔴 Undocumented |
| 02 | TeaTime Messaging | 🔴 Undocumented |
| 03 | Networking & Transport | 🔴 Undocumented |
| 04 | Scene Graph | 🔴 Undocumented |
| 05 | Rendering | 🔴 Undocumented |
| 06 | Resource Management | 🔴 Undocumented |
| 07 | Avatar & Navigation | 🟡 Breakpoints found, under investigation |
| 08 | Harness & Bootstrap | 🔴 Undocumented |
| 09 | Persistence & Snapshots | 🟡 TSnapshotReader nil data observed |
| 10 | Tweak UI | 🟡 Running in 32-bit, freezes in 64-bit |
| 11 | Security | 🔴 Undocumented |
| 12 | Sound | 🟡 OpenAL FFI errors observed |
| 13 | OS Integration | 🔴 Undocumented |
| 14 | AI Integration | 🔴 Undocumented |
| 15 | Creator Tools | 🔴 Undocumented |
| 16 | Backup & Serialization | 🔴 Undocumented |
| 17 | Replication & Forking | 🔴 Undocumented |
| 18 | Learning & Mastery | 🔴 Undocumented |
🔴 Undocumented 🟡 Under Investigation 🟢 Documented
---
## Getting Started
### Prerequisites
- 64-bit Slackware Linux (15.0 recommended) with alien-bob's compat32 libraries
- OR any 64-bit Linux with 32-bit compatibility libraries installed
- Squeak 4.3 (for the reference 32-bit Croquet image)
- Squeak 6.x 64-bit (for the port work)
### Setup Guides
- [Slackware 15.0 compat32 setup](docs/setup/slackware-compat32.md) — Hard-won guide
to tracking down every missing 32-bit library on Slackware
- Linux 32-bit Squeak setup *(coming soon)*
- Linux 64-bit Squeak setup *(coming soon)*
### Running the Reference Implementation
```bash
cd images/32bit/updatedKrestiavano-1.0.25
./25.sh # Launch Master
./25Slave.sh # Launch Slave (in a second terminal)
```
---
## Contributing
Different developers are encouraged to take ownership of individual subsystems.
The git workflow is:
```
master ← stable, documented, working
dev ← integration branch
subsystem/XX-Name ← your working branch
```
To work on a subsystem:
```bash
git checkout -b subsystem/02-TeaTime
# ... do your work ...
git push origin subsystem/02-TeaTime
# open a pull request / merge when ready
```
When documenting a subsystem, the goal is:
1. **What it does** — plain English description
2. **Key classes** — the Smalltalk classes involved and their responsibilities
3. **How it connects** — interactions with other subsystems
4. **Known issues** — anything broken or different between 32-bit and 64-bit
5. **Configuration** — how to start, stop, configure it
---
## Known Issues
- `TSimpleController restore: data` called with nil — snapshot handshake incomplete
between Master and Slave instances
- Tweak UI freezes and distorts display when loaded into Squeak 6.x image
- OpenAL spatial sound FFI calls failing: `Unable to find function address`
- Master/Slave connection stalls — TeaTime peer discovery needs investigation
---
## Architecture Diagrams
See `docs/architecture/` for Dia diagram files:
- `CroquetSDK.dia` — initial system overview diagram
- `Croquet64-Level0-SolarSystem.dia` — the 18-subsystem solar system map
---
## Acknowledgements
- Alan Kay, David Smith, and the original Croquet team
- Nikolay Suslov for the updated Krestiavano SDK
- The Squeak community for keeping the VM alive and moving forward
- alien-bob (Eric Hameleers) for the Slackware multilib/compat32 infrastructure
---
*README authored by Claude (Anthropic) in collaboration with wm, March 2026.*
*"One day I will understand networking." — wm, also March 2026.*