Build API

The core builder API is the canonical way to compile and instantiate object-separated EvoGym worlds.

For the stable public surface and compatibility-only symbols, see API Boundary.

Public types

`ObjectTemplate`

Compiled template for one object. Includes:

object identity and origin
local grid
local point/spring data
dynamic boxel collision geometry
generalized cell geometry for rendering and static collision
robot/deformation metadata
actuator mappings

`WorldTemplate`

Compiled world template containing:

world bounds
robot name
ordered ObjectTemplate entries
robot template index

`WorldTemplateSet`

Paired template wrapper:

primary
mirror
mirror_mode

Use this when you want primary/mirrored templates available together, typically for within-genome evaluation.

`StaticColliderData`

Precomputed static-terrain collider geometry omitted from dynamic SimState.

Key fields:

point_positions
cell_vertices
cell_vertex_count
cell_edge_a
cell_edge_b
surface_edge_mask
cell_types

`BuiltWorld`

Concrete built runtime payload containing:

sim_state
topology
constants
collision_data
static_collider_data
actuator_info
per_axis_info
deformation_info
robot_point_indices
robot_point_mask
dynamic_terrain_point_indices
fixed_terrain_sample_positions
render_info
grid_h
grid_w

Public functions

`compile_world_template(world, robot_name="robot")`

Compile a single WorldTemplate.

`compile_world_templates(world, robot_name="robot", mirror_mode="none")`

Compile a WorldTemplateSet.

Supported mirror_mode values:

"none"
"paired"

`instantiate_world(template, robot_override=None)`

Build a concrete BuiltWorld from a compiled template.

`robot_override`

robot_override lets you vary morphology inside the robot’s fixed local frame.

Rules:

shape must match the robot template grid exactly
use the same body-array orientation as add_from_array(...)
EMPTY disables cells inside that frame
supported robot voxel types can vary across overrides
slope values are rejected
terrain objects are never affected

Unsupported experimental slope cells

Slope ids remain in jax_evogym.constants and in internal legacy fixtures, but they are not part of the stable public build contract.

By default:

compile_world_template(...) rejects slope cells
compile_world_templates(...) rejects slope cells
public top-level imports do not export slope constants
the designer palette exposes only stable square-cell types

For internal slope investigations and legacy fixtures, pass:

compile_world_template(world, robot_name="robot", allow_experimental_slopes=True)

The experimental path preserves the old slope geometry/validation code while slopes remain geometry-only. Sloped edges receive normal collision response, but slope friction, support, grip, stiction, and persistent manifold behavior are disabled. Flat FIXED terrain friction is unaffected.