Build a world with mods

A world combines terrain, placed objects, and enabled mods. Your mod provides reusable content or rules; the world decides where and how to use them.

For example, a harbor world might use one mod for buildings, one for lights, and one for delivery gameplay. Each can be developed and tested separately.

1. Prepare a world you can edit

Create or open a world from My Worlds. Finish the terrain and spawn setup before testing gameplay. You need edit rights to place persistent objects; being able to join a world does not grant edit rights.

If you are starting with an existing world, use a private copy for development. The default Creator preview also uses a temporary clone of your chosen world.

2. Create the content your world needs

For a set of buildings, lamps, or props:

vibelands create harbor-props --template props-pack
cd harbor-props
npm install
npm run check
npm run dev

Choose the world when prompted and open the printed game link. The terminal reports build and preview status. Save a source file to apply another revision.

In your package, each editorItems entry adds an item to the Add library. Its matching objectRenderers component draws it. Follow the placeable object guide to add your own.

Preview and original world

The default preview is a separate world clone. Changes made there do not silently become edits to the original world. Keep track of which world the printed link opens. See Remote Sandbox.

3. Place and configure objects

In the preview's editor, open Add, select your item, and place it. Move, rotate, scale, duplicate, and delete it using the usual editor controls.

Use two kinds of settings:

Setting	Declare in the manifest	Example
Per-world mod setting	configSchema	All harbor lamps use a warm light color.
Per-object setting	editorItems[].propertySchema	This sign says “Harbor”; another says “Market”.

Read world settings with useModConfig() or ctx.config. Read object settings from the renderer's properties prop. The host validates these values.

4. Add gameplay as a separate feature

Start from a gameplay template when players must share an activity:

vibelands create harbor-hunt --template persistent-collectible

Use the server to validate player actions. Use client components to show the result. For interactions tied to placed objects, the server can read its owned objects through ctx.objects and validate proximity with findNearbyWorldObject. Declare world.objects.read and players.read.

Keep reusable props in a small content mod. Put activity rules in a gameplay mod when they have a separate lifecycle or settings. A single mod may also contain both when they belong to one feature. A mod cannot directly edit another mod's private state.

5. Check what survives

Content	Who owns it	What to verify
Terrain and editor placements	World editor	Rejoin the same world and check placement.
Enabled mod and configuration	World settings	Check the intended world has the correct mod version and settings.
ctx.entities and ctx.state	Running mod instance	Rebuild these when the world starts. They are not durable storage.
ctx.storage values	Mod, scoped to one world	Save successfully, restart, and load them again.
Account inventory or rewards	Host account services	Verify the actual result; these are separate from local world progress.

State and lifecycle explains these boundaries in detail.

6. Playtest with another player

Check the experience from a second client: join after the activity has started, perform an action, and confirm both players see the same result. Also check out-of-range actions, duplicate requests, reconnects, and a world restart.

Try low graphics quality and a dense area of placed objects. Use batch renderers for large repeated prop sets; keep single-object renderers for editor previews.

7. Share the mod and the world deliberately

A mod release distributes code and assets. A world contains the layout and configuration that use that code. Publishing a mod does not publish a world, and a successful Sandbox build is not a Marketplace release.

Follow Publishing to submit a mod for review. Once available, install and enable the intended version in your destination world through its mod store. Verify its items and settings there before inviting players.

World visibility controls who can discover or join it; editing policy controls who can change it. Official-world candidate publishing is an administrator workflow, separate from ordinary community-world creation.

Moving world data

World Package v2 records mod compatibility information. Private mod storage is excluded by default. Declare storageExport only for data intended to travel with a world; imported data must match the mod version and schema requirements. Do not use a world export as an account inventory or reward backup.