Terrain and backgrounds
Read this page as Markdown · All docs for AI agents
Use the editor
Open World in the editor's asset panel. Set Layout → Outdoor, then choose Meadow, Desert, Rocky or Flat. Change the size, hill height, roughness or seed. New seed generates a different arrangement; View terrain frames the landscape.
The central build area remains level. Place props and stations within X/Z ±half your selected Build area width (56–384 metres); the generated terrain extends around that area and is walkable. A player reaching the outer boundary returns to spawn. Changing the seed preserves your placed entities. Terrain settings support Undo and Redo.
Choose Sky or Lobby panorama under Background, or select Upload panorama. Accepted uploads appear in the same selector and can be reused in your other worlds. Adjust Background rotation ° to align the view with your layout.
Terrain and background changes are part of the draft. Save draft stores them; Publish queues the world update after current bets finish. Set Layout → Room to restore the enclosed room. This removes terrain and background settings from the draft; uploaded images remain in your library.
Prepare a panorama
Use a still PNG, JPEG or WebP with these limits:
| Property | Limit |
|---|---|
| Input file | 12,000,000 bytes |
| Width | 512–8192 pixels |
| Height | 256–4096 pixels |
| Aspect ratio | 2:1 through 8:1, width divided by height |
| Decoded pixels | 16,777,216 |
| Converted WebP | 8,000,000 bytes |
A seamless 2:1 equirectangular panorama, such as 4096 × 2048, covers the full sphere. A wider panorama, such as 8192 × 2048, covers a band around the horizon and fades into the sky above and below. Keep the horizon near the middle, align the left and right edges and bake the image in landscape orientation. Panoramas with a rotated EXIF orientation are rejected; export the actual pixels in the intended orientation first. The renderer softens the join and poles, but matching the source edges gives the best result.
The converter retains the source dimensions, strips metadata, flattens transparency and encodes a new WebP. Only the converted image is stored and displayed. SVG, GIF, animated WebP, archives and URLs are not accepted. Processing uses the isolated, networkless image worker.
Models and converted backgrounds share your 100 MB library allowance. A referenced panorama also counts toward the world's 100 MB download, 32 megapixel texture and 500 MB estimated memory limits. A maximum-size panorama may leave too little memory for a complex world; the save response reports the combined budget.
World document fields
Keep version: 1, floor, walls and entities. Add either or both of these optional fields:
{
"terrain": {
"preset": "desert",
"seed": 42,
"size": 256,
"height": 9,
"roughness": 0.45
},
"background": {
"mode": "lobby",
"yaw": 0
}
}
The example shows the environment fields to merge into your complete document.
| Terrain field | Required value |
|---|---|
preset | meadow, desert or rocky |
seed | Integer 0–2,147,483,647 |
size | Integer 128–512 and at least buildSize + 64; full square width in game units |
height | Finite number 0–28; maximum terrain amplitude |
roughness | Finite number 0–1; contribution of smaller hills |
The same settings generate the same terrain. Geometry uses a fixed 192 × 192 grid: 37,249 vertices and 73,728 triangles. The center remains flat through ±(buildSize / 2 + 6) units (±34 at the default build size), then transitions into hills. Collision uses the generated mesh. The return boundary is three units inside each outer edge. Terrain geometry counts toward the geometry and estimated memory budgets; the world stores only its parameters.
| Background field | Required value |
|---|---|
mode | sky, lobby or image |
yaw | Finite radians, −2π through 2π |
asset | Required only for image: a 64-character lowercase hex hash from your background library |
For an uploaded image:
{"mode":"image","asset":"<returned-background-hash>","yaw":1.5707963267948966}
Omit terrain for flat outdoor ground. Omit both terrain and background for the enclosed room. A background alone creates a square of flat ground with width max(128, buildSize + 64) and the floor color. Change the root buildSize field to enlarge the placement area. The editor automatically increases terrain width if enlarging the build area requires it; API clients must send compatible values together. Game dimensions remain unchanged. There is no separate background URL, shader or expression field.
Upload through HTTP
With a world-scoped Bearer credential:
curl --fail-with-body \
-X POST https://betworld.gg/api/worlds/ai/backgrounds/upload \
-H "Authorization: Bearer $BETWORLD_TOKEN" \
-H "Content-Type: image/webp" \
-H "X-Image-Name: Desert sunset" \
--data-binary @desert-panorama.webp
Send raw image bytes. Accepted content types are image/png, image/jpeg, image/webp and application/octet-stream. X-Image-Name is an optional trimmed name, 1–80 characters; it defaults to Panorama. Use ASCII for this HTTP header. The authenticated owner-session equivalent is POST /api/worlds/backgrounds.
Successful response, HTTP 201:
{
"hash": "<64-character-hash>",
"name": "Desert sunset",
"size": 1843200,
"width": 4096,
"height": 2048,
"pixels": 8388608
}
Download the converted result from GET /api/worlds/backgrounds/<hash>.webp. This immutable public route returns image/webp. A creator can reference only hashes in their own library, even when another creator's public image URL is known.
GET /api/worlds/mine, GET /api/worlds/:id/draft, GET /api/worlds/ai/draft/document and GET /api/worlds/ai/export/world include a backgrounds array with these metadata fields. The export also includes each background's url. /mine reports usedBytes for models and backgrounds together. The existing assets array continues to contain only GLB models.
After upload, fetch the latest draft, set document.background, and save the complete document with its current revision. Uploading alone does not modify or publish the world.
| Status | Meaning |
|---|---|
| 400 | Invalid fields, library quota, missing/foreign background, or world budget exceeded |
| 401 | Sign-in or world credential required |
| 404 | Background hash does not exist |
| 413 | Request body exceeds the upload limit |
| 422 | Image could not be converted within its format, dimension or processing limits |
| 429 | Request rate or concurrent-write limit reached |
| 503 | Converter is busy or unavailable; retry later |
Upload through MCP
Call background_upload with:
{
"name": "Desert sunset",
"imageBase64": "<base64-encoded-image-bytes>"
}
The decoded image has the same 12 MB limit. The tool returns the metadata shown above. Use world_download, update document.terrain and/or document.background, then call world_upload with the returned revision and the complete document. Preserve entities, game skins and any other settings. Publish from your owner session in Betworld.
The Blender bridge preserves terrain and background settings during download/upload round trips. Its scene preview still uses the base room shell; inspect the generated landscape and panorama in the in-game editor.