Interface IMyEntities

Provides API, that granting access to enitities (mods interface)

Namespace: VRage.ModAPI

Assembly: VRage.Game.dll

Syntax

public interface IMyEntities

Methods

AddEntity(IMyEntity, Boolean)

Registers entity

Declaration

void AddEntity(IMyEntity entity, bool insertIntoScene = true)

Parameters

Type	Name	Description
IMyEntity	entity	Entity that should be registered
System.Boolean	insertIntoScene	When true OnAddedToScene(Object) is called

CreateFromObjectBuilder(MyObjectBuilder_EntityBase)

Create entity from object builder

Declaration

IMyEntity CreateFromObjectBuilder(MyObjectBuilder_EntityBase objectBuilder)

Parameters

Type	Name	Description
MyObjectBuilder_EntityBase	objectBuilder	Object builder of entity

Returns

Type	Description
IMyEntity	Created entity

CreateFromObjectBuilderAndAdd(MyObjectBuilder_EntityBase)

Create entity from object builder, and then call AddEntity(IMyEntity, Boolean)

Declaration

IMyEntity CreateFromObjectBuilderAndAdd(MyObjectBuilder_EntityBase objectBuilder)

Parameters

Type	Name	Description
MyObjectBuilder_EntityBase	objectBuilder	Object builder of entity

Returns

Type	Description
IMyEntity	Created entity

CreateFromObjectBuilderNoinit(MyObjectBuilder_EntityBase)

Create new entity from objectBuilder, but doesn't call Init(MyObjectBuilder_EntityBase objectBuilder)

Declaration

IMyEntity CreateFromObjectBuilderNoinit(MyObjectBuilder_EntityBase objectBuilder)

Parameters

Type	Name	Description
MyObjectBuilder_EntityBase	objectBuilder

Returns

Type	Description
IMyEntity

CreateFromObjectBuilderParallel(MyObjectBuilder_EntityBase, Boolean, Action<IMyEntity>)

Creates and asynchronously initializes and entity.

Declaration

IMyEntity CreateFromObjectBuilderParallel(MyObjectBuilder_EntityBase objectBuilder, bool addToScene = false, Action<IMyEntity> completionCallback = null)

Parameters

Type	Name	Description
MyObjectBuilder_EntityBase	objectBuilder	Object builder of grid
System.Boolean	addToScene	Call AddEntity(IMyEntity, Boolean) and call OnAddedToScene
System.Action<IMyEntity>	completionCallback	Callback called in main thread.

Returns

Type	Description
IMyEntity	Create but not inited yet entity. Entity would be inited correctly after callback trigger

EnableEntityBoundingBoxDraw(IMyEntity, Boolean, Nullable<Vector4>, Single, Nullable<Vector3>)

Draw bounding box around entity

Declaration

void EnableEntityBoundingBoxDraw(IMyEntity entity, bool enable, Nullable<Vector4> color = null, float lineWidth = 0.01F, Nullable<Vector3> inflateAmount = null)

Parameters

Type	Name	Description
IMyEntity	entity	That should have visible bounding box
System.Boolean	enable	When true, bounding box start draw around entity
System.Nullable<Vector4>	color	Color of lines
System.Single	lineWidth	With of lines
System.Nullable<Vector3>	inflateAmount	Distance from original bounding box, from each side in meters

EntityExists(Int64)

Returns if entity with provided name exists

Declaration

bool EntityExists(long entityId)

Parameters

Type	Name	Description
System.Int64	entityId	EntityId

Returns

Type	Description
System.Boolean	True if entity exists

EntityExists(Nullable<Int64>)

Returns if entity with provided name exists

Declaration

bool EntityExists(Nullable<long> entityId)

Parameters

Type	Name	Description
System.Nullable<System.Int64>	entityId	EntityId

Returns

Type	Description
System.Boolean	True if entity exists

EntityExists(String)

Returns if entity with provided name exists

Declaration

bool EntityExists(string name)

Parameters

Type	Name	Description
System.String	name	Name

Returns

Type	Description
System.Boolean	True if entity exists

Exist(IMyEntity)

Checks if entity is registered entity

Declaration

bool Exist(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity to test

Returns

Type	Description
System.Boolean	True if entity is registered

FindFreePlace(Vector3D, Single, Int32, Int32, Single)

Use to find place that doesn't have any voxels, grids, or physical bodies. If original position can't fill check sphere, new position in some distance is picked. Distance grows each testsPerDistance attempts. Maximum distance from BasePos that can be used is calculated by formula: maxTestCount / testsPerDistance * radius * stepSize

Declaration

Nullable<Vector3D> FindFreePlace(Vector3D basePos, float radius, int maxTestCount = 20, int testsPerDistance = 5, float stepSize = 1F)

Parameters

Type	Name	Description
Vector3D	basePos	Base position
System.Single	radius	Radius in which there should be nothing
System.Int32	maxTestCount	How many tries should be done, to find free space
System.Int32	testsPerDistance	Depends how often distance from original position grows
System.Single	stepSize	How distance grows

Returns

Type	Description
System.Nullable<Vector3D>	Position that can doesn't have voxels, grids and other HkBodies in provided radius

GetElementsInBox(ref BoundingBoxD)

Returns list of entities that intersects with BoundingBox. This function will return CubeBlocks. This function works slower than GetTopMostEntitiesInBox(ref BoundingBoxD)

Declaration

List<IMyEntity> GetElementsInBox(ref BoundingBoxD boundingBox)

Parameters

Type	Name	Description
BoundingBoxD	boundingBox	Bounding box in world coordinates

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	New list of entities

Remarks

Same as GetEntitiesInAABB(ref BoundingBoxD)

GetEntities(HashSet<IMyEntity>, Func<IMyEntity, Boolean>)

Get all entities matching condition

Declaration

void GetEntities(HashSet<IMyEntity> entities, Func<IMyEntity, bool> collect = null)

Parameters

Type	Name	Description
System.Collections.Generic.HashSet<IMyEntity>	entities	This set would receive results. Can be null, but then collect function should always return false
System.Func<IMyEntity, System.Boolean>	collect	When it is null or returns true, provided hashset adds entity

GetEntitiesInAABB(ref BoundingBoxD)

Returns list of entities that intersects with BoundingBox. This function will return CubeBlocks. This function works slower than GetTopMostEntitiesInBox(ref BoundingBoxD)

Declaration

List<IMyEntity> GetEntitiesInAABB(ref BoundingBoxD boundingBox)

Parameters

Type	Name	Description
BoundingBoxD	boundingBox	Bounding box in world coordinates

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	New list of entities

Remarks

Same as GetElementsInBox(ref BoundingBoxD)

GetEntitiesInSphere(ref BoundingSphereD)

Returns list of entities that intersects with sphere. This function will return CubeBlocks. This function works slower than GetTopMostEntitiesInSphere(ref BoundingSphereD)

Declaration

List<IMyEntity> GetEntitiesInSphere(ref BoundingSphereD boundingSphere)

Parameters

Type	Name	Description
BoundingSphereD	boundingSphere	Bounding sphere in world coordinates

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	New list of entities

GetEntity(Func<IMyEntity, Boolean>)

Get first entity that matching condition

Declaration

IMyEntity GetEntity(Func<IMyEntity, bool> match)

Parameters

Type	Name	Description
System.Func<IMyEntity, System.Boolean>	match	When return true, this entity would be used as a return value

Returns

Type	Description
IMyEntity	First matching condition entity

GetEntityById(Int64)

Returns entity with provided entityId

Declaration

IMyEntity GetEntityById(long entityId)

Parameters

Type	Name	Description
System.Int64	entityId	EntityId

Returns

Type	Description
IMyEntity	Entity with provided id, or null

GetEntityById(Nullable<Int64>)

Returns entity with provided entityId

Declaration

IMyEntity GetEntityById(Nullable<long> entityId)

Parameters

Type	Name	Description
System.Nullable<System.Int64>	entityId	EntityId

Returns

Type	Description
IMyEntity	Entity with provided id, or null

GetEntityByName(String)

Returns entity with provided name

Declaration

IMyEntity GetEntityByName(string name)

Parameters

Type	Name	Description
System.String	name	Name

Returns

Type	Description
IMyEntity	Entity with registered Name or null

GetInflatedPlayerBoundingBox(ref BoundingBox, Single)

Declaration

void GetInflatedPlayerBoundingBox(ref BoundingBox playerBox, float inflation)

Parameters

Type	Name	Description
BoundingBox	playerBox
System.Single	inflation

GetInflatedPlayerBoundingBox(ref BoundingBoxD, Single)

Making playerBox include all connected players

Declaration

void GetInflatedPlayerBoundingBox(ref BoundingBoxD playerBox, float inflation)

Parameters

Type	Name	Description
BoundingBoxD	playerBox	Box, that would contain all players
System.Single	inflation	Minimal distance between player, and border

GetIntersectionWithSphere(ref BoundingSphereD)

Returns first found (not closest) entity that intersects with sphere

Declaration

IMyEntity GetIntersectionWithSphere(ref BoundingSphereD sphere)

Parameters

Type	Name	Description
BoundingSphereD	sphere	Sphere to test (in world coordinates)

Returns

Type	Description
IMyEntity	First found entity

GetIntersectionWithSphere(ref BoundingSphereD, IMyEntity, IMyEntity)

Returns first found (not closest) entity that intersects with sphere

Declaration

IMyEntity GetIntersectionWithSphere(ref BoundingSphereD sphere, IMyEntity ignoreEntity0, IMyEntity ignoreEntity1)

Parameters

Type	Name	Description
BoundingSphereD	sphere	Sphere to test (in world coordinates)
IMyEntity	ignoreEntity0	Return value can't be this entity
IMyEntity	ignoreEntity1	Return value can't be this entity

Returns

Type	Description
IMyEntity	First found entity, or null

GetIntersectionWithSphere(ref BoundingSphereD, IMyEntity, IMyEntity, Boolean, Boolean)

Returns list of entities that intersects with sphere

Declaration

List<IMyEntity> GetIntersectionWithSphere(ref BoundingSphereD sphere, IMyEntity ignoreEntity0, IMyEntity ignoreEntity1, bool ignoreVoxelMaps, bool volumetricTest)

Parameters

Type	Name	Description
BoundingSphereD	sphere	Sphere to test (in world coordinates)
IMyEntity	ignoreEntity0	Returned list can't contain this entity
IMyEntity	ignoreEntity1	Returned list can't contain this entity
System.Boolean	ignoreVoxelMaps	When true, voxels won't checked
System.Boolean	volumetricTest	When false physical shape checking used. It is much more accurate, but slower

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	List of entities inside of sphere

Remarks

Returned list may be used by system, next call if this or other similar function will clear list, so if you need to store data for long time, copy data from it. Also clean list, after you don't need it anymore

GetIntersectionWithSphere(ref BoundingSphereD, IMyEntity, IMyEntity, Boolean, Boolean, Boolean, Boolean, Boolean)

Returns first found (not closest) entity that intersects with sphere

Declaration

IMyEntity GetIntersectionWithSphere(ref BoundingSphereD sphere, IMyEntity ignoreEntity0, IMyEntity ignoreEntity1, bool ignoreVoxelMaps, bool volumetricTest, bool excludeEntitiesWithDisabledPhysics = false, bool ignoreFloatingObjects = true, bool ignoreHandWeapons = true)

Parameters

Type	Name	Description
BoundingSphereD	sphere	Sphere to test (in world coordinates)
IMyEntity	ignoreEntity0	Return value can't be this entity
IMyEntity	ignoreEntity1	Return value can't be this entity
System.Boolean	ignoreVoxelMaps	When true, voxels won't checked
System.Boolean	volumetricTest	When false physical shape checking used. It is much more accurate, but slower
System.Boolean	excludeEntitiesWithDisabledPhysics	When true, entities with disabled physics won't checked
System.Boolean	ignoreFloatingObjects	When true, floating objects won't checked
System.Boolean	ignoreHandWeapons	When true, hand weapons (tools) won't checked

Returns

Type	Description
IMyEntity	Found entity matching conditions

GetTopMostEntitiesInBox(ref BoundingBoxD)

Returns list of TopMost entities that intersects with bounding box. This function won't return CubeBlocks. Use GetElementsInBox(ref BoundingBoxD) to retrieve CubeBlocks also.

Declaration

List<IMyEntity> GetTopMostEntitiesInBox(ref BoundingBoxD boundingBox)

Parameters

Type	Name	Description
BoundingBoxD	boundingBox	Bounding box in world coordinates

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	New list of entities

GetTopMostEntitiesInSphere(ref BoundingSphereD)

Returns list of TopMost entities that intersects with sphere. This function won't return CubeBlocks. Use GetEntitiesInSphere(ref BoundingSphereD) to retrieve CubeBlocks also.

Declaration

List<IMyEntity> GetTopMostEntitiesInSphere(ref BoundingSphereD boundingSphere)

Parameters

Type	Name	Description
BoundingSphereD	boundingSphere	Bounding sphere in world coordinates

Returns

Type	Description
System.Collections.Generic.List<IMyEntity>	New list of entities

IsInsideVoxel(Vector3, Vector3, out Vector3)

Declaration

bool IsInsideVoxel(Vector3 pos, Vector3 hintPosition, out Vector3 lastOutsidePos)

Parameters

Type	Name	Description
Vector3	pos
Vector3	hintPosition
Vector3	lastOutsidePos

Returns

Type	Description
System.Boolean

IsInsideVoxel(Vector3D, Vector3D, out Vector3D)

Return true if line between pos and hintPosition doesn't intersect any voxel, or intersects it even number of times Does inside physical ray casting inside

Declaration

bool IsInsideVoxel(Vector3D pos, Vector3D hintPosition, out Vector3D lastOutsidePos)

Parameters

Type	Name	Description
Vector3D	pos	Position of object
Vector3D	hintPosition	Position of object few frames back to test whether object entered voxel. Usually pos - LinearVelocity * x, where x it time.
Vector3D	lastOutsidePos	Last position that was outside of voxels

Returns

Type	Description
System.Boolean

IsInsideWorld(Vector3D)

Returns true if distance from 0,0,0 to provided position is less than WorldHalfExtent()

Declaration

bool IsInsideWorld(Vector3D pos)

Parameters

Type	Name	Description
Vector3D	pos	Checked position in world coordinates

Returns

Type	Description
System.Boolean	True if distance is less than WorldHalfExtent()

IsNameExists(IMyEntity, String)

Checks if registered name belongs to this entity

Declaration

bool IsNameExists(IMyEntity entity, string name)

Parameters

Type	Name	Description
IMyEntity	entity	Entity to test
System.String	name	Name to test

Returns

Type	Description
System.Boolean	True if registered name belongs to this entity

IsRaycastBlocked(Vector3D, Vector3D)

Returns true if raycast hits anything (with raycast layer=0)

Declaration

bool IsRaycastBlocked(Vector3D pos, Vector3D target)

Parameters

Type	Name	Description
Vector3D	pos	From
Vector3D	target	To

Returns

Type	Description
System.Boolean

IsSpherePenetrating(ref BoundingSphereD)

Checks if sphere hits any Havok.HkRigidBody

Declaration

bool IsSpherePenetrating(ref BoundingSphereD bs)

Parameters

Type	Name	Description
BoundingSphereD	bs	Sphere that used for intersection check

Returns

Type	Description
System.Boolean	True if sphere hits any body

IsTypeHidden(Type)

Gets whether entities that inherit type is visible or not. Example:

IsTypeHidden(typeof (IMyCubeGrid))

Declaration

bool IsTypeHidden(Type type)

Parameters

Type	Name	Description
System.Type	type

Returns

Type	Description
System.Boolean

IsVisible(IMyEntity)

Gets whether entity is visible or not because of SetTypeHidden(Type, Boolean)

Declaration

bool IsVisible(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity

Returns

Type	Description
System.Boolean	True when visible

IsWorldLimited()

Return whether world has limited size in kilometers

Declaration

bool IsWorldLimited()

Returns

Type	Description
System.Boolean	True if limited

MarkForClose(IMyEntity)

Mark entity as closed. Soon it would be deleted. Doesn't call Close()

Declaration

void MarkForClose(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity to close

RegisterForDraw(IMyEntity)

Make entity receive PrepareForDraw and sending to it's Render Draw call

Declaration

void RegisterForDraw(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	That should be drawn

RegisterForUpdate(IMyEntity)

Make entity receive UpdateBeforeSimulation, UpdateBefore10Simulation, UpdateBefore100Simulation, UpdateAfterSimulation, UpdateAfter10Simulation, UpdateAfter100Simulation, Simulate, UpdateBeforeNextFrame depending on it's NeedsUpdate flags. Physics are still simulated

Declaration

void RegisterForUpdate(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	That should have updates

RemapObjectBuilder(MyObjectBuilder_EntityBase)

Remaps this entity's EntityId and Name to a new values.

Declaration

void RemapObjectBuilder(MyObjectBuilder_EntityBase objectBuilder)

Parameters

Type	Name	Description
MyObjectBuilder_EntityBase	objectBuilder	ObjectBuilder that should be remapped

RemapObjectBuilderCollection(IEnumerable<MyObjectBuilder_EntityBase>)

Remaps this entity's EntityId and Name to a new values.

Declaration

void RemapObjectBuilderCollection(IEnumerable<MyObjectBuilder_EntityBase> objectBuilders)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<MyObjectBuilder_EntityBase>	objectBuilders	ObjectBuilders that should be remapped

RemoveEntity(IMyEntity)

Unregisters entity

Declaration

void RemoveEntity(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity that should be unregistered

RemoveFromClosedEntities(IMyEntity)

Remove entity from lists of closed entities

Declaration

void RemoveFromClosedEntities(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity that should be removed

RemoveName(IMyEntity)

Removes registered name from entity.

Declaration

void RemoveName(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity, that has name

SetEntityName(IMyEntity, Boolean)

Apply Name for entity

Declaration

void SetEntityName(IMyEntity IMyEntity, bool possibleRename = true)

Parameters

Type	Name	Description
IMyEntity	IMyEntity	Entity that should be named
System.Boolean	possibleRename	Allows renaming

SetTypeHidden(Type, Boolean)

Entities that inherit that type would be visible/invisible.

Declaration

void SetTypeHidden(Type type, bool hidden)

Parameters

Type	Name	Description
System.Type	type	Type that class should inherit to be invisible, ex: IMyCubeGrid
System.Boolean	hidden	Sets if inherited entities should be visible visible or not

TryGetEntityById(Int64, out IMyEntity)

Returns entity with provided id

Declaration

bool TryGetEntityById(long id, out IMyEntity entity)

Parameters

Type	Name	Description
System.Int64	id	EntityId
IMyEntity	entity	Found entity

Returns

Type	Description
System.Boolean	True if entity is found

TryGetEntityById(Nullable<Int64>, out IMyEntity)

Returns entity with provided id

Declaration

bool TryGetEntityById(Nullable<long> id, out IMyEntity entity)

Parameters

Type	Name	Description
System.Nullable<System.Int64>	id	EntityId
IMyEntity	entity	Found entity

Returns

Type	Description
System.Boolean	True if entity is found

TryGetEntityByName(String, out IMyEntity)

Returns entity with provided name

Declaration

bool TryGetEntityByName(string name, out IMyEntity entity)

Parameters

Type	Name	Description
System.String	name	Name
IMyEntity	entity	Found entity

Returns

Type	Description
System.Boolean	True if entity is found

UnhideAllTypes()

Revert all changes to default. Make all entities visible, that were hidden because of SetTypeHidden(Type, Boolean)

Declaration

void UnhideAllTypes()

UnregisterForDraw(IMyEntity)

Unregistering entity from PrepareForDraw events and it Render from Draw calls. Entity may still be rendered

Declaration

void UnregisterForDraw(IMyEntity entity)

Parameters

Type	Name	Description
IMyEntity	entity	Entity that should stop receive draw calls

UnregisterForUpdate(IMyEntity, Boolean)

Unregistering entity from following updates: UpdateBeforeSimulation, UpdateBefore10Simulation, UpdateBefore100Simulation, UpdateAfterSimulation, UpdateAfter10Simulation, UpdateAfter100Simulation, Simulate, UpdateBeforeNextFrame Physics are still simulated

Declaration

void UnregisterForUpdate(IMyEntity entity, bool immediate = false)

Parameters

Type	Name	Description
IMyEntity	entity	Entity that should not receive updates anymore
System.Boolean	immediate	When true, updates removed immediately, but may cause crashes

WorldHalfExtent()

Returns shortest distance (i.e. axis-aligned) to the world border from the world center. Will be 0 if world is borderless

Declaration

float WorldHalfExtent()

Returns

Type	Description
System.Single

WorldSafeHalfExtent()

Returns shortest distance (i.e. axis-aligned) to the world border from the world center, minus 600m to make spawning somewhat safer. Will be 0 if world is borderless

Declaration

float WorldSafeHalfExtent()

Returns

Type	Description
System.Single

Events

OnCloseAll

Called when session unloads, before grids are closed

Declaration

event Action OnCloseAll

Event Type

Type	Description
System.Action

OnEntityAdd

Called when AddEntity(IMyEntity, Boolean) called on entity

Declaration

event Action<IMyEntity> OnEntityAdd

Event Type

Type	Description
System.Action<IMyEntity>

OnEntityNameSet

Called when entity gets Name. First string - old name, Second - new name

Declaration

event Action<IMyEntity, string, string> OnEntityNameSet

Event Type

Type	Description
System.Action<IMyEntity, System.String, System.String>

OnEntityRemove

Called when RemoveEntity(IMyEntity) called on entity

Declaration

event Action<IMyEntity> OnEntityRemove

Event Type

Type	Description
System.Action<IMyEntity>

See Also

IMyEntity