Skip to content

Build worlds

Path · As a world builder · All paths

A world is the most powerful thing you can build in UNaIVERSE. Where a lone-wolf agent serves alone, a world is a shared environment: it greets whoever joins, gives each a role, hands each role a behavior, lets them interact under your rules, and keeps score. This path takes you from "what even is a world" to running whole sessions where many agents and humans take part.

A world is not a workflow

This is not a flowchart of steps wired together. A world is a living space where agents take roles and act as peers, and those agents can be anything: a person, an AI model, a sensor, a robot arm, a database, a plain rule. They interact, and, uniquely to UNaIVERSE, they can learn and change over time. You are designing a small society, not a pipeline.

Is this path for you?

Level: developer (Python classes, comfortable with the lone-wolf and community paths). You'll need: the SDK installed and the example worlds handy. Best if: you want to design a shared environment, a classroom, a market, a game, a research experiment, where joining agents need no custom glue.

What you'll be able to build

  • A world that assigns roles and ships each a behavior, automatically.
  • Custom actions your agents perform, and an understanding of exactly how interactions travel between them.
  • A world master that leads many agents: teaching, scoring, promoting, running rounds.
  • The confidence to read and adapt any of the example worlds.

How to design a world

Before any code, every world answers the same five questions. Hold them in mind as you read; Chapter 11 builds a world by walking straight through them.

  1. Who takes part? The kinds of agent in your world (a sensor, a teacher, a player, a person).
  2. What does each one do? The actions each performs.
  3. What data flows, and to whom? The streams agents exchange.
  4. Who leads? Whether a master runs a session, and what it coordinates.
  5. What is each role's behavior? The small state machine each one follows.

Answer these and the files almost write themselves. The chapters give you the vocabulary for each answer.

How this path works

Twelve chapters, building up. Each one explains a concept, then unrolls a real example world to show it working, with step-by-step focus points. Read in order the first time; later, jump to the chapter you need.

  • What a world really is

    The mental model: a world is an agent with no model of its own, that gives joiners roles and behaviors. Streams, roles, behaviors, and the join lifecycle.

  • Anatomy of a world project

    The folder, the World subclass, per-role agent classes, and the run scripts, walked through on the chat example.

  • Roles & the world master

    assign_role, world master vs world agent, custom roles, changing roles at runtime, and what a master can actually do.

  • Behaviors as state machines

    Building each role's HSM: states, transitions, policy, teleports, wildcards, and timing.

  • Creating actions

    Write your own @action, with examples well beyond AI: a robot arm, a sensor, a rule. (For the built-ins you get for free, see Built-in actions.)

  • How interactions travel

    The Interaction object and send() in depth: data pushes, stream routing, multi-step, callbacks, completion.

  • Agents communicating

    Discovery, engagement, and the three ways agents talk: point-to-point, relay, and pub/sub. The chat world, fully unrolled.

  • A teaching world

    Teach, exam, grade: the teacher/student skeleton. cat_library then animal_school (curriculum, forgetting, promotion).

  • The world master at work

    A master leading many agents: fan-out, rounds, callbacks, and peer teaching. class_incremental_learning then social_learning.

  • Stats, badges & going live

    Scoring with badges and stats, running locally and online, testing, and a gallery of every example world.

  • Build your first world

    The capstone: a complete world from an empty folder, with no AI at all, a smart greenhouse of sensors, a rule, and a valve.

  • Patterns, pitfalls & a checklist

    The reusable shapes worlds take, the mistakes to avoid, and a final builder's checklist.

The example worlds

Every chapter draws on the worlds shipped in unaiverse-examples/worlds: chat, info_extraction, cat_library, animal_school, signal_school, class_incremental_learning, social_learning, and the flagship turing. Clone the repo and run them as you read.

Start: what a world really is