bbi.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
class Asset(node_id: str, asset_class: str | None = None, asset_name: str | None = None, position: Vector3 = Vector3.zero(), rotation: Vector3 = Vector3.zero(), scale: Vector3 = Vector3(1, 1, 1), randomize: bool = False)

Bases: Node, Animatable[AssetUpdateParam]

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

  • If asset_name is provided, the specific asset will be spawned.

  • If asset_class is provided, a random asset from that class will be spawned. If randomize is set to True,

the asset will be randomized on every frame.

Parameters:

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

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

  • 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).

  • randomize (bool, optional) – Randomize the asset on each frame, only applicable for asset_class. Defaults to False.

property size: Vector3
property centroid_offset: Vector3

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

property asset_name: str
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.

is_static() → bool

Returns True if the Asset spawns a single static 3D model.

If is_static() returns False, then the asset is randomized and spawns random 3D models with a class defined by asset_class.

If asset_name is provided on creation, the Asset is considered static.

is_randomized() → bool

Returns True if the Asset spawns random 3D models with a defined class.

If is_randomized() returns False, then the asset is static and spawns a single 3D model defined by asset_name.

If asset_name is not provided on creation, the Asset is considered randomized.

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 | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None

Update the asset state up to the specified frame.

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.

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.

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 | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None

Update the spawnzone state up to the specified frame.

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.

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

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

Bases: Asset, Animatable[BuoyantAssetUpdateParam]

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

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 | None = None, frame_max: int | None = None, delta_seconds: float | None = None) → None

Update the asset state up to the specified frame.

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.