Struct ark_api::world::World

pub struct World { /* private fields */ }

World implements the low-level entity API and the mesh API.

For ease of development, the wrappers (Entity, Environment etc) are recommended for entity management.

Implementations

impl World

pub fn instance_mut() -> impl DerefMut<Target = World>

Get the World singleton.

pub fn instance() -> impl Deref<Target = World>

Get the World singleton.

pub fn create_entity(name: &str, entity_template: EntityTemplate) -> Entity

Creates a world entity, from one of several templates (entity_type).

• name: only relevant for keeping track of your object during development

• entity_template: Chooses between one of a few “templates” (sets of precreated components):

  • EntityTemplate::Empty
  • EntityTemplate::Object
  • EntityTemplate::Environment
  • EntityTemplate::MeshStyle
  • EntityTemplate::Camera

pub fn add_component(entity: Entity, component_type: ComponentType)

Adds a component to an entity.

pub fn remove_component(entity: Entity, component_type: ComponentType)

Removes a component from an entity.

pub fn has_component(entity: Entity, component_type: ComponentType) -> bool

Checks whether an entity has a component.

pub fn destroy_entity(entity: Entity)

Destroys an entity. Attempting to access the entity after this is an error.

pub fn clone_entity(name: &str, entity_src: Entity) -> Entity

Clones an entity with all its components and returns the handle to the new entity.

pub fn clone_entities(
    name: &str,
    entity_dst: &mut [Entity],
    entity_src: &[Entity]
)

Clones multiple entities with all their components and returns the handles to the new entities.

The name passed will be concatenated to the name of each source entity.

pub fn copy_component(
    entity_dst: Entity,
    entity_src: Entity,
    component_type: ComponentType
)

Copies a component from an entity to another. Creates the component if it doesn’t exists.

pub fn is_valid_entity(entity: Entity) -> bool

Lets you check whether an EntityHandle points to a valid entity.

If it has existed but been destroyed, the return value is false.

pub fn set_entity_value(
    entity: Entity,
    component: ComponentType,
    param_id: u32,
    value: &Value
)

Sets the value of a property of a component belonging to an entity.

pub fn get_entity_value(
    entity: Entity,
    component: ComponentType,
    param_id: u32
) -> Value

Gets the value of a property of a component belonging to an entity.

pub fn get_entity_values<T: Sized>(
    entities: &[Entity],
    value_type: EntityValueType,
    out_data: &mut Vec<T>
) -> Result<(), Error>

Retrieves values of the entities passed through the slice entities.

Careful attention that the out_data element size and layout matches the corresponding EntityValueType struct, should be taken.

pub fn set_entity_values<T: Sized>(
    entities: &[Entity],
    value_type: EntityValueType,
    in_data: &[T]
) -> Result<(), Error>

Sets the values of the entities passed through the slice entities. The length of the out_data slice needs to be the same as entities or a single value in which case it will be applied to all entities.

Careful attention that the in_data element size and layout matches the corresponding EntityValueType struct, should be taken.

pub fn set_entity_local_transforms(
    entities: &[Entity],
    input: &[EntityTransform]
)

Sets the local transforms of the entities passed through the slice entities. The length of the input slice needs to be the same as entities or a single value in which case it will be applied to all entities.

pub fn get_entity_local_transforms(
    entities: &[Entity],
    output: &mut Vec<EntityTransform>
)

Retrieves the local transforms of the entities passed through the slice entities.

pub fn set_entity_world_transforms_affine3(
    entities: &[Entity],
    input: &[EntityTransformAffine3]
)

Sets the world transforms of the entities passed through the slice entities. The length of the input slice needs to be the same as entities or a single value in which case it will be applied to all entities.

pub fn get_entity_world_transforms_affine3(
    entities: &[Entity],
    output: &mut Vec<EntityTransformAffine3>
)

Retrieves the world transforms of the entities passed through the slice entities.

pub fn get_entities_state(
    entities: &[Entity],
    output: &mut Vec<EntityStateFlags>
)

Retrieves the state of the local transforms of the entities passed through the slice entities.

It is useful to call this method before World::get_entity_local_transforms to figure out which entities actually have the value.

pub fn set_entity_world_transforms(
    entities: &[Entity],
    input: &[EntityTransform]
)

Sets the world transforms of the entities passed through the slice entities. The length of the input slice needs to be the same as entities or a single value in which case it will be applied to all entities.

pub fn get_entity_world_transforms(
    entities: &[Entity],
    output: &mut Vec<EntityTransform>
)

Retrieves the world transforms of the entities passed through the slice entities.

pub fn get_entity_local_bounds(
    entities: &[Entity],
    output: &mut Vec<EntityBounds>
)

Retrieves the local bounds of the entities passed through the slice entities.

pub fn get_entity_physics_velocities(
    entities: &[Entity],
    output: &mut Vec<EntityVelocity>
)

Retrieves the physics velocities of the entities passed through the slice entities.

pub fn set_entity_render_tints(
    entities: &[Entity],
    input: &[EntityMeshStyleTint]
)

Sets the mesh style tints referenced from the entities passed through the slice entities. The length of the input slice needs to be the same as entities or a single value in which case it will be applied to all the entities.

Note: Will set the tint on the mesh style that is used by this entity. This assumes each entity uses its own MeshStyle.

pub fn set_entity_render_enables(
    entities: &[Entity],
    input: &[EntityRenderEnable]
)

Sets if rendering is enabled for the entities passed through the slice entities. The length of the input slice needs to be the same as entities or a single value in which case it will be applied to all the entities.

pub fn create_body_immediate(entity: Entity)

Creates a physics body in the middle of the frame

Takes parameters from the Physics component. Automatically used by the World API in enable_dynamic and similar functions.

pub fn get_mesh_properties(mesh_handle: DataHandle) -> MeshProperties

Lets you query some properties of a raw mesh, including its bounding volume.

pub fn get_mesh_morph_target_names(mesh_handle: DataHandle) -> Vec<String>

Lets you query the names of any morph targets associated with the mesh.

It is recommended to store the return value instead of calling it every frame.

pub fn is_valid_mesh(mesh_handle: DataHandle) -> bool

Lets you check whether a DataHandle points to a valid mesh.

If it has existed but been destroyed, the return value is false.

pub fn raycast(raycast: &RaycastQuery) -> Option<RaycastHit>

Casts a ray through the world, returning the first hit.

You can also use this to do spherecasts (a.k.a sphere sweeps or “thick” raycasts) by setting RaycastQuery::spherecast_radius.

pub fn raycast_batched(
    raycasts: impl Iterator<Item = RaycastQuery>
) -> Vec<Option<RaycastHit>>

Casts multiple rays through the world, returning the first hit for each. This is faster than calling raycast multiple times.

You can also use this to do spherecasts (a.k.a sphere sweeps or “thick” raycasts) by setting RaycastQuery::spherecast_radius.

pub fn ray_cast(
    ray_origin: Vec3,
    ray_dir: Vec3,
    min_t: f32,
    max_t: f32,
    any_hit: bool,
    exclude_entity: Entity
) -> Option<(Entity, f32)>

👎Deprecated:

Use raycast instead

Casts a ray through the world (SLOW!).

Reports the first hit or optionally any hit, which can be somewhat faster to compute, but which hit you get is not guaranteed in any way).

One entity can be excluded to avoid self-hits.

pub fn send_messages(entity: Entity, messages: &[Message])

Sends multiple messages to an entity.

pub fn retrieve_messages(entity: Entity) -> Vec<Message>

Retrieves a copy of the entity’s outbox as a Vec

pub fn get_components(entity: Entity, components: &mut [ComponentType]) -> u32

Gets all components an entity has, returns the number of components.

pub fn get_components_vec(entity: Entity) -> Vec<ComponentType>

Gets all components an entity has

pub fn create_data(create_data_type: CreateDataType, data: &[u8]) -> DataHandle

Creates a new data object from a CreateDataType and slice of bytes.

pub fn retrieve_data(
    data_handle: DataHandle,
    retrieve_data_type: RetrieveDataType,
    out_data: &mut [u8]
) -> u32

Gets data from the data referenced by the handle. Always returns the number of bytes even if the output is empty (so you can allocate the right amount)

pub fn retrieve_data_vec(
    data_handle: DataHandle,
    retrieve_data_type: RetrieveDataType
) -> Vec<u8>

Retrieves data by this DataHandle and RetrieveDataType as a Vec of bytes.

pub fn destroy_data(data: DataHandle)

Decreases the ref count of a data object. When ref count reaches zero it is destroyed. Attempting to access the data after this is an error.

pub fn retain_data(data: DataHandle)

Increases the ref count of a data object.

pub fn is_valid_data(data_handle: DataHandle) -> bool

Lets you check whether a DataHandle points to a valid data object. If it has existed but been destroyed, the return value is false.

pub fn set_data_debug_name(data_handle: DataHandle, name: &str)

Sets a debug name of this data object. Useful for debugging memory usage and leaks.

pub fn get_data_debug_name(data_handle: DataHandle) -> String

Gets a debug name of this data object.

pub fn set_entity_debug_options(entities: &[Entity], options: EntityDebugOptions)

Sets debug options of this entity such as whether to enable physics shape debug rendering or not. An empty slice will mean to apply the options to all entities in the world.

pub fn update<F: FnOnce()>(f: F)

Pass your world update function to this. Will make sure messages are received, sent and transient entities are destroyed in the right order.

pub fn measure_formatted_text(
    formatted_text: &FormattedText
) -> MeasuredTextSize

Measures the layout size of a chunk of formatted text. Formatting is embedded directly into the string using a simple markup language, documented elsewhere.