bbi.spawn.spawn

pydantic model AssetUpdateParam

Bases: AnimationFrame

field asset_name: str | None = None
field position: Vector3 | None = None
field rotation: Vector3 | None = None
field scale: Vector3 | None = None
field thermal_glass_brightness: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
field thermal_max_temperature: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
field thermal_min_temperature: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
field thermal_opacity: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
field thermal_reflectivity: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
field thermal_temperature: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | None = None
class Asset(node_id: str, asset_name: str, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1))

Bases: Node, Animatable[AssetUpdateParam]

Asset class which holds the 3D model data and information.

Parameters:

  • node_id (str) – The user defined unique ID.

  • asset_name (str, optional) – The name of the asset.

  • position (Vector3, optional) – The position of the asset. Defaults to Vector3.zero().

  • rotation (Vector3, optional) – The rotation of the asset. Defaults to Vector3.zero().

  • scale (Vector3, optional) – The scale of the asset. Defaults to Vector3(1, 1, 1).

property size: Vector3
property centroid_offset: Vector3

The offset to add to the asset position to get the centroid of the asset.

property centroid: Vector3

The centroid of the asset.

property bounding_cuboid: Cuboid

The bounding cuboid of the asset.

property asset_name: str
property thermal: AssetThermal

Thermal properties and methods of the asset.

set_transform(transform: Transform) → None

Set the transform of the instance. For efficiency, this method is preferred over setting individual transform components.

Parameters:

transform (Transform) – The transform.

get_collisions() → set[str]

Get the names of all assets that collide with the current asset.

attach_to(parent: Node, rule: TransformAttachmentRule = TransformAttachmentRule.KEEP_WORLD) → None

Attach the asset to another node inheriting its transform operations.

Parameters:

  • parent (Node) – The parent node to attach the asset to.

  • rule (TransformAttachmentRule, optional) – How to handle transforms and welding when attaching, defaults to TransformAttachmentRule.KEEP_WORLD.

attach_to_root() → None

Attach the asset to its root node.

execute(frame_id: int, frame_max: int, delta_seconds: float) → None

Update the asset state up to the specified frame.

Parameters:

  • frame_id (int) – The frame ID.

  • frame_max (int) – Max frame count in the current loop

  • delta_seconds (float) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets.

enable_wake(is_enabled: bool) → None

Enables or disables the wake effect on the asset.

Parameters:

is_enabled (bool) – Whether to enable or disable the wake effect.

set_collision_check(check: bool) → None

Whether the asset should be included in collision checks.

When enabled, this asset will be considered during collision detection with other assets being added or moved in the spatial index. When disabled, this asset will be ignored during such checks.

Parameters:

check (bool) – Whether to perform collision checks for this asset.

set_thermal_brightness(value: float) → None

Set the thermal brightness of the asset.

A value of 0 represents the darkest thermal state, while a value of 1 represents the brightest thermal state.

Deprecated since version Use: asset.thermal.set_temperature() instead. This method will be removed in a future version.

Parameters:

value (float) – The thermal brightness value between 0 and 1

set_thermal_color_variation(value: float) → None

Set the thermal color variation of the asset.

A value of 0 represents no color variation, while a value of 1 represents maximum color variation.

Deprecated since version This: method is deprecated and will be removed in a future version.

Parameters:

value (float) – The thermal color variation value between 0 and 1

set_thermal_opacity(value: float) → None

Set the thermal opacity of the asset.

A value of 0 represents completely transparent, while a value of 1 represents completely opaque.

Deprecated since version Use: asset.thermal.set_opacity() instead. This method will be removed in a future version.

Parameters:

value (float) – The thermal opacity value between 0 and 1

set_thermal_glass_brightness(value: float) → None

Set the thermal glass brightness of the asset.

A value of 0 represents the darkest glass brightness state, while a value of 1 represents the brightest glass brightness state.

Deprecated since version Use: asset.thermal.set_glass_brightness() instead. This method will be removed in a future version.

Parameters:

value (float) – The thermal glass brightness value between 0 and 1

set_static_wake(wake_type: StaticWakeType, pattern: KelvinWakeTypes | FoamWakeTypes | None, local_position: Vector3 = Vector3.zero(), local_rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3.one(), opacity: float = 1.0) → None

Set a static wake effect on the asset.

Parameters:

  • wake_type (StaticWakeType) – The type of static wake effect to apply.

  • pattern (KelvinWakeTypes | FoamWakeTypes | None) – The pattern for the wake effect.

  • local_position (Vector3, optional) – Local position relative to parent. Defaults to Vector3.zero().

  • local_rotation (Vector3, optional) – Local rotation (Euler angles) relative to parent. Defaults to Vector3.zero().

  • scale (Vector3, optional) – Local scale relative to parent. Defaults to Vector3.one().

  • opacity (float, optional) – Opacity of the wake effect. Defaults to 1.0.

pydantic model SpawnZoneUpdateParam

Bases: AnimationFrame

Validators:
field asset_names: list[str] | None = None
Validated by:
field asset_weights: list[float] | None = None
Validated by:
field contain_within: bool | None = None
Validated by:
field force_respawn: bool | None = None
Validated by:
field geometry: list[Geometry] | Geometry | None = None
Validated by:
field jitter_z: tuple[float, float] | None = None
Validated by:
field pitch_range: tuple[float, float] | None = None
Validated by:
field quantity: Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])] | None = None
Validated by:
field roll_range: tuple[float, float] | None = None
Validated by:
field use_geom_rotation: bool | None = None
Validated by:
field yaw_range: tuple[float, float] | None = None
Validated by:
validator check_names_and_weights  »  all fields
validator set_default_weights  »  all fields
class SpawnZone(node_id: str, asset_names: list[str], quantity: int, geometry: Geometry | list[Geometry], asset_type: type[Asset] = Asset, yaw_range: tuple[float, float] = (0, 360), pitch_range: tuple[float, float] = (0, 0), roll_range: tuple[float, float] = (0, 0), asset_weights: list[float] | None = None, force_respawn: bool = False, contain_within: bool = True, jitter_z: tuple[float, float] = (0, 0), use_geom_rotation: bool = True)

Bases: Node, Animatable[SpawnZoneUpdateParam]

Random scattering of assets within a defined zone.

Parameters:

  • node_id (str) – The node ID of the zone.

  • asset_names (list[str]) – The names of the assets to spawn.

  • quantity (int) – The max number of objects to spawn. The final number of spawned assets might be less than this number if there are not enough valid spawn locations, most often due to collisions.

  • geometry (Geometry, list[Geometry]) – The geometry that defines the spawn zone.

  • asset_type (type[Asset], optional) – The type of asset to spawn. Defaults to Asset.

  • yaw_range (tuple[float, float], optional) – The yaw range for the assets. Defaults to (0, 360). If the geometry is a Spline, the yaw would be set to the tangent of the spline at the spawn position, unless use_geom_rotation is set to False.

  • roll_range (tuple[float, float], optional) – The roll range for the assets. Defaults to (0, 0). This has no effect on BuoyantAsset.

  • pitch_range (tuple[float, float], optional) – The pitch range for the assets. Defaults to (0, 0). If the geometry is a Spline, the pitch would be set to the normal of the spline at the spawn position. This has no effect on BuoyantAsset.

  • asset_weights (list[float], optional) – The distribution of assets when spawning. If not provided, all assets are equally likely to be spawned.

  • force_respawn (bool, optional) – Forcibly remove all existing assets and spawn new ones at each frame, even if the SpawnZone parameters have not changed. If SpawnZone parameters are changed, assets are always respawned regardless of the value of force_respawn. Defaults to False.

  • contain_within (bool, optional) – Make assets spawn contained entirely within the geometry (Polygon or Cuboid). If True, assets will not clip the edges of the boundary. If False, assets may extend beyond the boundary. Defaults to True.

  • jitter_z (tuple[float, float], optional) – The range of z-axis jitter applied to the assets after they are spawned. Defaults to (0, 0).

  • use_geom_rotation (bool, optional) – Whether to use the intrinsic rotation of the geometry (e.g. Spline). Defaults to True.

execute(frame_id: int, frame_max: int, delta_seconds: float) → None

Update the spawnzone state up to the specified frame.

Parameters:

  • frame_id (int) – The frame ID.

  • frame_max (int) – Max frame count in the current loop.

  • delta_seconds (float) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets.

pre_execute(frame_id: int | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None

Removes spawned assets if respawning is needed. This is to ensure that the old assets are not present during collision checks, especially in the case where there are multiple SpawnZones and they overlap

Parameters:

  • frame_id (int | None, optional) – The frame ID. Defaults to None.

  • frame_max (int | None, optional) – Max frame count in the current loop. Defaults to None.

  • delta_seconds (float | None, optional) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets. Defaults to None.

pydantic model BuoyantAssetUpdateParam

Bases: AssetUpdateParam

Validators:

  • _validate_rotation » rotation

field sinking_offset: float | None = None
class BuoyantAsset(node_id: str, asset_name: str, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1))

Bases: Asset, Animatable[BuoyantAssetUpdateParam]

Assets which floats on water and has a buoyant physics effect.

Wake generation is automatically disabled for extra small assets to prevent unnecessary computational overhead. You can override this using enable_wake().

set_transform(transform: Transform) → None

Set the transform of the instance. For efficiency, this method is preferred over setting individual transform components.

Parameters:

transform (Transform) – The transform.

set_sinking_offset(sinking_offset: float) → None

Set the sinking offset for the buoyant asset.

Parameters:

sinking_offset (float) – The offset value (in meters) for the sinking effect.

set_buoyancy_damping(damping: float) → None

Set the buoyancy damping of the buoyant asset.

Parameters:

damping (float) – The rate at which rotation should chase buoyancy. A value of 1.0 means that the asset will be as buoyant as the ocean, and a value of 0.0 means that the asset will have no buoyancy at all.

execute(frame_id: int, frame_max: int, delta_seconds: float) → None

Update the asset state up to the specified frame.

Parameters:

  • frame_id (int) – The frame ID.

  • frame_max (int) – Max frame count in the current loop

  • delta_seconds (float) – The target real-time in seconds between frames. This is used to calculate physical displacement for certain assets.

pydantic model BillboardAssetUpdateParam

Bases: AssetUpdateParam

class BillboardAsset(node_id: str, asset_name: str, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1))

Bases: Asset, Animatable[BillboardAssetUpdateParam]

Assets which automatically rotate to face the camera at all times.