Building

What a World Is Made Of

A Space's world is the contents of its Workspace: parts, the Models and Folders that group them, terrain, and the lights and labels that sit among them. The sun, sky and atmosphere belong to the Lighting service. Parts, Models, Folders and lights are objects with a class, a name and properties: the Explorer lists them, the Properties panel edits them, and scripts and AI agents reach them the same way.

Adding Things

• Toolbox: the Primitives row inserts the six shapes with one click.
• Model tab: the Part, Model and Folder buttons, and Point and Spot for lights.
• Insert Object (Ctrl+I): every insertable class, grouped by category.

A new part appears 10 m in front of the camera, gray, Plastic and unanchored, and arrives selected. With a Model or Folder selected in the Explorer, it goes inside that container instead. Inserts from the Model tab and Insert Object copy the class's template, a small file shipped with Studio, so every new object starts with a complete set of properties. The panels and tools you use from here are covered in Studio.

Shapes and Meshes

A part is a Part object: one mesh, scaled to a size in meters, with a color and a material. The six built-in shapes are glTF meshes built to a 1 m cube, so a part's size is simply the scale applied to its mesh. The shape also decides the collider physics uses.

Point a part at any other glTF file and it becomes a custom-mesh part, what other tools call a MeshPart. Eustress has one Part class for both and reads a MeshPart class name as Part. Bringing meshes and whole models in is covered in Importing.

A mesh named like a shape loads the shape

Studio recognizes the built-in shapes by file name: a mesh whose file name contains block, ball, cylinder, wedge or cone is drawn with the built-in shape of that name, so traffic_cone.glb renders as the stock cone. Keep those words out of custom mesh names. A Part file with no mesh at all is a block, and so is a part whose custom mesh is missing on disk.

Properties

The Properties panel shows a part's values under Transform, Appearance and Physics, with Rotation in degrees and a BrickColor picker beside Color. In the part's file they are these keys; the defaults are the Part template's:

In Studio every part with a collider is static. Entering Play turns unanchored parts that have a collider into moving bodies; how they move, dent and break is covered in Physics.

Meters

The world is measured in meters: one unit is one meter in files, physics, raycasts and gizmos alike. A file may declare another authoring unit, and Studio converts its position and size to meters as it loads:

[metadata]
class_name = "Part"
unit = "cm"                    # m, cm, mm, ft or in

[asset]
mesh = "parts/cylinder.glb"

[transform]
position = [0.0, 50.0, 0.0]    # 0.5 m up
scale = [10.0, 100.0, 10.0]    # 0.1 x 1.0 x 0.1 m

The unit badge in the status bar picks the unit the Properties panel displays lengths in. It is a view setting: it never rewrites a file.

On Disk

An object that owns files is a folder in the Space: a part with its own mesh, anything with children, scripts and GUI. The folder holds an _instance.toml and the files it owns, and the folder name is the object's name. You can write one by hand while Studio runs; the file watcher spawns it.

[metadata]
class_name = "Part"
archivable = true

[asset]
mesh = "parts/block.glb"
scene = "Scene0"

[transform]
position = [0.0, 1.0, 0.0]
rotation = [0.0, 0.0, 0.0, 1.0]
scale = [2.0, 2.0, 2.0]

[properties]
color = [150, 111, 51]
material = "WoodPlanks"
anchored = true
can_collide = true

Plain primitive parts do not need a folder. In a Space with its database (the default), a shape inserted from the Toolbox at the top level of the Workspace is stored as a compact record in the Space's world.fjalldb, which is how a Space holds very large numbers of parts. Either way it loads as the same Part. How the database and the files relate, and how history is kept, is covered in Universes.

Models and Folders

A Model groups parts into one object: click any part of a Model in the viewport and the whole Model is selected, while Alt + click selects just that part. A Folder only organizes. It can hold anything, and its contents still select one at a time. Neither has geometry of its own.

Insert either one from the Model tab or Insert Object, keep it selected, and insert parts: they go inside it. Objects saved as folders can also be dragged onto it in the Explorer. The move is made on disk and in the Space's database together, and one Ctrl+Z undoes it.

Group and Ungroup

Ctrl+G wraps two or more selected objects in a new Model placed at the average of their positions. Ctrl+U dissolves each selected Model or Folder and lifts its children one level up. Neither moves anything in the world, and each is a single undo step however much is selected. Both also sit in the Edit group of the Home tab.

Ctrl+G groups for this session only

The Model that Ctrl+G creates is not written to the Space, so it is gone the next time the Space opens. For a group you want to keep, insert a Model first and build inside it.

Booleans

The Boolean group on the Drafting tab turns two or more selected parts into one new part, computed as an exact solid by the same kernel as CAD. Select the parts, then click:

The result is a part named UnionResult, SubtractResult or IntersectResult, anchored, with the color and material of the first part. Its mesh is saved as result.glb in its folder, so it survives a reload. The source parts are removed; those saved as folders go to the Space's trash, and one Ctrl+Z brings them back and removes the result.

Boolean Limits

• Shapes: blocks and cylinders are cut exactly. Balls are cut as cubes, cones as straight cylinders and wedges as their bounding blocks, and the notice after the operation names any shape it approximated.
• Collision: the result collides as a box the size of its bounds.
• Failures: when the kernel cannot build a solid (coplanar faces, for example), the selection is grouped into a Model instead and the notice says why.
• Baked: the result is plain geometry. To change a cut, undo it, adjust the parts and run it again.

The Library

A material is a named surface: its color maps, bumpiness, roughness and metalness. A part's material takes one of 22 built-in names:

Plastic, SmoothPlastic, Wood, WoodPlanks, Metal, CorrodedMetal, DiamondPlate, Foil, Grass, Concrete, Brick, Granite, Marble, Slate, Sand, Fabric, Glass, Neon, Ice, Gold, Silver, Bronze.

Each has a definition file in the Space's MaterialService folder, and Studio copies in any that are missing when a Space opens. Eighteen carry 2048 x 2048 texture maps drawn to repeat every 4 m and to wrap edge to edge, so a long wall shows brick-sized bricks with no visible joins. Plastic, SmoothPlastic, Glass and Neon are plain surfaces with no maps.

Material Files

A material file has three tables: [material] names it and picks a preset (the built-in material whose roughness, metalness and reflectance fill any factor left out), [pbr] holds factors that multiply the maps, and [textures] names the maps. This is the library's Brick:

[material]
name = "Brick"
preset = "Brick"
description = "Red brick in running bond, 25 x 8.3 cm courses in recessed mortar"

[pbr]
base_color = [1.0, 1.0, 1.0, 1.0]
metallic = 0.0
roughness = 1.0
reflectance = 0.5

# metallic_roughness is packed glTF-style: R = occlusion, G = roughness, B = metallic.
[textures]
base_color = "materials/textures/brick_base_color.png"
normal = "materials/textures/brick_normal.png"
metallic_roughness = "materials/textures/brick_metallic_roughness.png"
occlusion = "materials/textures/brick_metallic_roughness.png"

Map paths resolve next to the material file first and in the bundled library second. The loader also reads emissive and depth maps, and in [pbr]: alpha_mode (opaque, blend or mask, with alpha_cutoff), double_sided, unlit, emissive, and ior, specular_transmission, diffuse_transmission and thickness for see-through materials.

To add your own, drop a new .mat.toml into MaterialService (it loads while the Space is open) and set a part's material to its name: the name in [material], or the file name when that is empty. The MaterialService entry in Services covers the registry behind it.

Color, Tiling and Glow

A part's color multiplies its material. The library maps are colored, so a white part shows a map as drawn and a tinted part tints it. Tiling follows the part's size: blocks, wedges and corner wedges get the texture laid flat on each face with one repeat per 4 m of the broad faces, balls wrap it around, and cylinders, cones and custom meshes use their own texture coordinates, scaled by their two largest dimensions.

• Reflectance adds to a material's metalness and cuts its roughness by up to half, so any material can be polished.
• Transparency above 0 blends the part with what is behind it. Glass is smooth and highly reflective; give it some transparency to see through it.
• Neon glows: it emits the part's color at twice its strength.
• Maps load only when a part first uses the material, and each gets a full chain of smaller versions (mipmaps) so distant surfaces stay smooth. KTX2, DDS and Basis files bring their own.

Making Terrain

Terrain is a heightfield: one ground surface for the Space, stored as a grid of heights and cut into square chunks that draw, collide and save on their own. Making terrain replaces any terrain already there. The Terrain tab offers:

The Terrain panel (Terrain in the left panel's overflow menu) adds flat plates of 320 m and 1.1 km, and Generate World, which takes your own seed: the same seed and size always produce the same world. The ribbon's Small, Medium and Large use seed 42.

Clear, Generate and Import cannot be undone

Clear deletes Workspace/Terrain from disk straight away, and Generate, Flat and Import overwrite it. Commit the Space to git or copy the folder first if you might want the old terrain back.

Sculpting and Painting

Click Edit on the Terrain tab, or pick a brush, then drag across the ground. While editing, 1 to 5 choose Raise, Lower, Smooth, Flatten and Paint, and [ and ] shrink and grow the brush in 2 m steps between 1 and 50 m (it starts at 8 m). Each stroke is one undo step, named Sculpt Terrain or Paint Terrain, and Save writes both the heights and the paint.

• Paint lays the grass layer; nothing in Studio picks another layer yet.
• Region and Fill are not built; clicking them says so and keeps the current brush.
• Look: terrain is colored per vertex from four weights (grass, rock, dirt, snow) with slope and curvature shading, not textured.
• Shape: one height per point, so there are no caves or overhangs, and heights stay inside the band the terrain was made with.

Every chunk has a heightfield collider built from its full-detail heights, so falling parts and raycasts stop at the ground, and a chunk's collider is rebuilt a moment after you stop editing it. Farther chunks draw with fewer samples.

Terrain on Disk

Terrain lives in Workspace/Terrain: a settings file, one 16-bit height file per chunk under chunks/, and one paint image per chunk under splatmap/ whose red, green, blue and alpha channels hold the grass, rock, dirt and snow weights. The settings file the Flat plate writes begins:

[terrain]
chunk_size = 64.0          # meters per chunk side
chunk_resolution = 64      # height samples per chunk side
height_scale = 128.0       # height band, meters
height_offset = -32.0      # world Y of the lowest height
seed = 0

[streaming]
view_distance = 256.0      # chunks cover -4 to +4 around the origin

A height sample's world Y is height_offset plus its 16-bit value, scaled to height_scale. Terrain imported with a Roblox place arrives as voxels in the Space's database, and Studio shows its top surface; see Importing.

Roads

In Civil mode, the Plugins tab carries a Road Builder. Add Node places road points on the terrain with each click (right-click or Esc finishes), Apply to Terrain cuts and fills the ground along a smooth curve through them and lays a road surface on top, and Remove Road deletes the road and restores the ground. Ctrl+Z reverses the ground changes either one makes.

Light Objects

A light object adds a real light to the scene. A PointLight shines in every direction, a SpotLight in a cone, and a DirectionalLight in parallel rays across the whole Space, like the sun. A SurfaceLight currently shines as a point light from where it sits. Changes in the Properties panel apply to the light at once.

Studio budgets point and spot lights by distance to the camera, so a Space can hold thousands; see Render Distance and Lights.

Sun and Time of Day

The sun, moon, sky and atmosphere belong to the Lighting service, and a new Space gets Sun, Moon, Sky and Atmosphere objects inside it. Select Lighting in the Explorer to set the time and the overall light:

In Studio the sun stays where ClockTime puts it. The sun dims toward the horizon and gives no light once it is 6 degrees below it. During Play the simulation clock moves the time of day forward; the clock is covered in Simulation.

Sky and Shadows

The sky is drawn by a physically based atmosphere model, which scatters sunlight the way air does, so its color follows the sun through the day, and the sun itself warms toward the horizon. At night a star field and a moon disc showing its current phase appear. The sun casts shadows in four cascades out to 1,000 m from the camera.

Labels and Particles

A BillboardGui is a text or image label that floats in the world and always faces the camera; building one is covered in UI Systems. The Particle Sim button on the Model tab inserts a physical particle simulation (fluids, electrons, conduction), covered in Realism.

Repetition Is Cheap

Every part of the same shape shares one mesh, and every part with the same look (material, color, transparency and reflectance, plus tiling on a textured material) shares one GPU material, so identical parts are drawn together in batches. A build that reuses a palette of colors and materials draws far faster than one where every part is a slightly different shade. When a Space is too big to load in a single frame, Studio also rounds colors to 16 levels per channel so near-identical shades share a material.

Shadows are the other big cost: the sun renders every shadow caster again into each of its four shadow cascades, out to 1,000 m. Switch CastShadow off on parts nobody will see a shadow from, such as trim, interiors and anything under a roof.

Render Distance and Lights

The Workspace's RenderDistance property (Rendering, 5,000 m in a new Space) is how far away parts are drawn. A part stops drawing once the nearest point of its bounding sphere is beyond that distance, so a large baseplate stays visible while you stand on it. Editing the value applies to every part at once.

Lights are budgeted by distance to the camera. The 64 nearest point and spot lights shine; farther ones go dark beyond 350 m and relight within 250 m. The 32 nearest cast shadows and the rest do not, whatever their own shadow setting says. The list is refreshed after 5 m of camera travel or every 30 frames.

Streaming Very Large Spaces

When a Space's database holds more than 100,000 objects, Studio stops loading everything at open. It loads the parts within 350 m of the camera and unloads them past 500 m, saving edits first and never unloading the selection. Everything farther away is drawn as stand-ins: one merged mesh per 256 m cell, built once in the background from the cell's shaped parts and cut to about a tenth of their triangles, at most 2,000 per cell. A cell's stand-in hides as the real parts around the camera take over.

• Stand-ins can't be selected, cast no shadows, and leave out custom meshes and transparent parts.
• They are built when the Space opens and not rebuilt, so the distant view shows a session's edits after the Space reopens.
• Colliders in a streaming Space are created during Play only near moving bodies, the player and the camera (within 128 m), which keeps physics cost flat however big the map is.

Exact Booleans for Every Shape

Booleans will cut balls, cones and wedges as their true shapes once the solid kernel builds those shapes directly. Until then the notice after each operation names every approximation it made, so a cut that comes out boxy is never a mystery.

Surface Effects

Decals, tiled textures, beams between attachments and particle emitters will draw in the viewport. Their classes already exist and can be inserted; the renderers that draw them come next, together with light cookies, the patterned textures a light can project.

Mesh Editing

Custom meshes will get a face-editing mode in Studio. The half-edge editing kernel it will use is already in the repository and extrudes and insets faces; bevel and loop cut will follow before the mode ships.

More Terrain Tools

The Region and Fill brushes already sit on the Terrain tab and will do real work once they are built, and Paint will gain a choice of layer beyond grass, using the rock, dirt and snow channels the paint maps already carry.