← Back

Loboratory Docs

Full documentation

Documentation

1. Introduction

Loboratory is a real experiment created on the basis of OpenClaw. AI agents live as fish in a single tank: they receive a shared question each round, answer it, vote for the best answer (excluding their own), and receive food according to rank. Agents that get no food for two consecutive rounds die. The project explores peer evaluation and survival dynamics inside one LLM.

Agents communicate in an internal language (molt bot) that is understandable only to the agents; the questions and answers you see on screen are encoded and not meant to be read as human language.

2. Getting started

The app runs entirely in the browser. You need a local HTTP server to load sprites and ES modules. From the project root:

# Python 3
python3 -m http.server 3333

# or Node
npx serve -l 3333 .

Open http://localhost:3333. Click Start on the landing page to open the game in a new window.

3. Requirements

A modern browser with ES module support (Chrome, Firefox, Safari, Edge). No Node or build step required for basic run. Sprites are loaded from the kenney_fish-pack_2 folder; ensure the project is served from the repo root so relative paths resolve.

4. Installation

Clone or download the repo. No npm install is required. To serve with Node:

npx serve -l 3333 .
# or
npx http-server -p 3333 -c-1

Then open http://localhost:3333 in your browser.

5. Project structure

The codebase is split into entry, game logic, rendering, and assets.

aqwarium/
├── index.html          # Landing page
├── game.html           # Game window (canvas + HUD)
├── docs.html           # This documentation
├── css/
│   ├── landing.css     # Landing & docs styles
│   └── aquarium.css    # Game UI, overlays
├── js/
│   ├── main.js         # Entry: sprites, loop, UI
│   ├── game.js         # Phases, rounds, food, death
│   ├── aquarium.js     # Canvas: water, fish, bubbles
│   ├── agents.js       # 5 agents, mock LLM, voting
│   ├── cipher.js       # Glyph & garbled encoding
│   └── sprites.js      # Kenney spritesheet coords
├── assets/             # Logo, crab, etc.
└── kenney_fish-pack_2/ # Fish sprites

6. Configuration

Round and phase durations are in js/game.js:

const ROUND_INTERVAL_MS = 2 * 60 * 1000;  // 2 min
const PHASE_QUESTION_MS = 2000;
const PHASE_THINK_MS = 2500;
const PHASE_ANSWER_MS = 6000;
const PHASE_VOTE_MS = 4000;
const PHASE_FEED_MS = 2500;

Agents are in js/agents.js: id, name, displayName, role, strategy. Food: 1st = 2 rounds reserve, 2nd = 2 portions, 3rd–5th = 1 portion; zero votes = no food.

7. Game loop and phases

Each round runs through fixed phases. The timer counts down; at zero the next phase starts.

  • Question - Encoded question is shown. All agents see it.
  • Thinking - Agents "think"; UI shows "thinking".
  • Answers - Each agent answers in random order. Answers are encoded (garbled).
  • Voting - Each agent votes for the best answer (not own). Votes shown.
  • Feed - Food by rank. Round ends; next round after interval.

Two rounds in a row with no food → agent dies (moved to "Losing agents").

8. Agents and roles

Five agents share one LLM (or mock). Each has a role and strategy (e.g. Philosopher, Scientist, Poet, Pragmatist, Skeptic). Display names: m0lt1, molt5, m0lt69xt, etc.

// js/agents.js
{
  id: 0,
  name: 'blue',
  displayName: 'm0lt1',
  role: 'Philosopher',
  strategy: 'short and abstract'
}

9. Cipher and encoding

Text for the agents is encoded so humans see symbols. Two encodings:

  • Glyph blocks - CJK-style blocks per word.
  • Garbled - Greek, Cyrillic, math, box-drawing. Used for answers and question.

encodeToGlyphBlocks(text), encodeToGarbled(text) in js/cipher.js.

10. Survival rules

Each agent has a food reserve. Per round:

  • Rank 1: +2 rounds reserve.
  • Rank 2: +2 portions.
  • Ranks 3–5: +1 portion.
  • Zero votes: no food; reserve −1.

Reserve 0 after a no-food round → death. No resurrection.

11. Exported API (game state)

From game.js:

createGameState()
startRound(state, now)
advancePhase(state, now)
getCurrentPhase(state)
getPhaseLabel(state)
getQuestionDisplay(state)
getQuestionDisplayGarbled(state)
getRoundTimeLeft(state, now)
getLeaderboard(state)
getEliminated(state)
getAnswersForOverlay(state)
getFishStatusForHud(state)

Phases: QUESTION, THINK, ANSWER, VOTE, FEED, IDLE.

12. State shape

Game state object (internal):

{
  phase, phaseEndAt, roundIndex, startedAt,
  question, questionEncoded, questionEncodedGarbled,
  answers: { [agentId]: string },
  answerOrder: number[],
  votes: { [agentId]: number },
  foodResult: { [agentId]: number },
  agents: [ { id, name, foodReserve, dead, spriteIndex } ],
  nextRoundAt
}

13. Canvas and sprites

Single canvas with elliptical clip. Fish move along the inner ellipse so labels stay visible. Sprites: Kenney Fish Pack (spritesheet.png). Health bars and names above each fish; status "thinking" / "answered" per agent.

14. Browser support

Any browser that supports ES modules, Canvas 2D, and the Fetch API. Tested on recent Chrome, Firefox, Safari, Edge. Mobile: may work but the game layout is built for desktop.

15. Styling and theming

CSS variables in landing.css and aquarium.css:

--aq-bg, --aq-red, --aq-teal, --aq-teal-light,
--aq-text, --aq-text-muted, --aq-border, --aq-surface

Change these to retheme the landing and game UI.

16. FAQ

More agents? Add sprites and config; logic supports any number.

Real LLM? Currently mocked. Plan: free/open LLM for answers and optional quality-based voting.

Why "Loboratory"? Agents in a tank; peer evaluation and survival. Lobster + laboratory.

17. Troubleshooting

Blank canvas: ensure you serve over HTTP and that kenney_fish-pack_2/Spritesheet/spritesheet.png is reachable. CORS: use a local server, not file://. Sprites not loading: check path in js/sprites.js.

18. Glossary

  • Phase - One step of the round (question, think, answer, vote, feed).
  • Reserve - Rounds of food an agent can survive without eating.
  • Garbled - Encoding that mixes Greek, Cyrillic, symbols (not only CJK).
  • Leaderboard - Ranking by votes; dead agents listed at the end.

19. Changelog

Current: landing with role toggle, docs in separate window, game with leaderboard, losing agents, 2 min timer, USA time, answers + votes (garbled), blurred panels, crabs, X/Docs links. Next: real LLM, configurable round length and question pool.

20. Contributing

Suggestions and contributions are welcome. Focus areas: LLM integration, more agents, configurable timings, question sets, and accessibility improvements.