Photon Quantum 3.0.0

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | List of all members
Quantum.DynamicMap Class Reference

Used to dynamically edit and manage mesh colliders and their triangles at runtime. This is particularly useful in games with procedurally generated content or user-generated levels, where the environment can change dynamically. More...

Inheritance diagram for Quantum.DynamicMap:
Quantum.Map

Public Member Functions

int AddCollider2D (FrameBase f, MapStaticCollider2D collider, bool resetPhysics=true)
 Adds a 2D collider to the map. More...
 
int AddCollider3D (FrameBase f, MapStaticCollider3D collider, bool resetPhysics=true)
 Adds a 3D collider (non-mesh) to the map. More...
 
int AddMeshCollider (FrameBase f, IList< FPVector3 > vertices, IList< int > indices=null, int additionalCapacity=0, StaticColliderData? staticData=default, bool resetPhysics=true, FPVector3? position=null, FPQuaternion? rotation=null, AssetRef< PhysicsMaterial >? material=null, bool smoothSphereCollisions=false)
 Adds a mesh collider to the map. More...
 
EditMeshScope EditMeshTriangles (FrameBase f, int meshColliderIndex)
 Edits the triangles of a mesh collider within a specific scope. When the scope is disposed, the changes are applied to the map. More...
 
override void Loaded (IResourceManager resourceManager, Native.Allocator allocator)
 Called when the map asset is loaded. More...
 
void RemoveAllColliders2D (FrameBase f)
 Removes all 2D colliders. More...
 
void RemoveAllColliders3D (FrameBase f)
 Removes all 3D colliders. More...
 
bool RemoveCollider2D (FrameBase f, int colliderId, bool resetPhysics=true)
 Removes a 2D collider from the map. More...
 
bool RemoveCollider3D (FrameBase f, int colliderId, bool resetPhysics=true)
 Removes a 3D collider from the map. More...
 
bool RemoveMeshCollider (FrameBase f, int meshColliderId, bool resetPhysics=true)
 Removes a mesh collider from the map. More...
 
bool ReserveMeshColliders (FrameBase f, int count, int capacity, StaticColliderData? staticData=null, bool resetPhysics=true)
 Pre-allocates space for a specified number of mesh colliders. More...
 
- Public Member Functions inherited from Quantum.Map
override void Disposed (IResourceManager resourceManager, Native.Allocator allocator)
 Called by the resource manager when the map asset was disposed to release memory. More...
 
void EnsurePhysicsWorldSizeInValidRange ()
 Post-process and clamp the physics world size. More...
 
NavMesh GetNavMesh (String name)
 Get namvesh by name. More...
 
Int32 GetStaticColliderTrianglesSerializedSize (bool isWriting)
 Get the serialized size of the static collider triangles data. More...
 
override void Loaded (IResourceManager resourceManager, Native.Allocator allocator)
 Called by the resource manager when the map asset was loaded. Used to deserialize map data allocate memory and initialize map data structures. More...
 
void SerializeStaticColliderTriangles (ByteStream stream, Native.Allocator allocator, Boolean write)
 Serialize or deserialize the static collider triangles data. More...
 

Static Public Member Functions

static T FromStaticMap< T > (Map map)
 Converts a static map to a dynamic map. More...
 

Public Attributes

List< FreeTriangle > FreeTrianglePool = new List<FreeTriangle>()
 Free triangles that can be used to store new triangles. More...
 
AssetRef< MapSourceMap
 The source map that was used to create this dynamic map. More...
 
- Public Attributes inherited from Quantum.Map
UnmanagedTriangleArray AllRuntimeTriangles = new UnmanagedTriangleArray()
 The unmanaged buffer containing all static triangles for this map. More...
 
PhysicsCommon.BucketAxis BucketingAxis = PhysicsCommon.BucketAxis.X
 Physics entries are put into buckets according to their position in the bucketing axis. More...
 
Int32 BucketsCount = 16
 The amount of buckets used in the broad phase, which are resolved in parallel. Use a reasonable amount according to how many physics entries (colliders) you have. Too many buckets and the handling overhead increases without any performance gain because there are only few entries in each one; too few buckets and there will be an excessive amount of entries in each, slowing down the broad phase performance. More...
 
Int32 BucketsSubdivisions = 8
 Regular queries (overlaps and raycasts) use a stabbing approach for checking as few entries as possible in the buckets subdivisions. Tweak the number in accordance with the expected amount of entries and regular queries you perform. Too many subdivisions will add overhead without performance, while too few will result in queries taking longer to resolve, because they will have to check too many entries. More...
 
SortedDictionary< int, MeshTriangleVerticesCcw > CollidersManagedTriangles = new SortedDictionary<Int32, MeshTriangleVerticesCcw>()
 The edit-time lookup for 3D static collider triangles. More...
 
SortedDictionary< int, MeshUnmanagedTrianglesRefCollidersRuntimeTriangles = new SortedDictionary<Int32, MeshUnmanagedTrianglesRef>()
 The runtime lookup for 3D static collider triangles. More...
 
Int32 GridNodeSize = 4
 The number of Unity units per navmesh grid cell. Must be multiple of 2. More...
 
Int32 GridSizeX = 64
 Number of navmesh grid cells in x-dimension. Toggle Navmesh Grid or Navmesh Area gizmos to preview. More...
 
Int32 GridSizeY = 64
 Number of navmesh grid cells in y-dimension. Toggle Navmesh Grid or Navmesh Area gizmos to preview. More...
 
ComponentPrototypeSet[] MapEntities = Array.Empty<ComponentPrototypeSet>()
 The list of entities baked into this map. More...
 
Dictionary< String, NavMeshNavMeshes
 The lookup table for navmeshes. Use navmesh names to find the navmesh object. The mapping is created during the asset Loaded callback. More...
 
AssetRef< NavMesh >[] NavMeshLinks = Array.Empty<AssetRef<NavMesh>>()
 The list not navmesh assets baked into this map. More...
 
Dictionary< String, Int32 > RegionMap
 The region map lookup table. Use region names to find the region index. The mapping is created during the asset Loaded callback. More...
 
string[] Regions = Array.Empty<string>()
 The list of navmesh region names baked into this map. More...
 
String Scene
 The Unity scene name is baked into the map. It's loaded automatically if Simulation.AutoLoadSceneFromMap is enabled. More...
 
String SceneGuid
 The Unity scene guid is baked into the map for convenience. More...
 
FP SceneMeshCellSize = FP._4
 Defines the size of the cells into which the 3D triangle soup is divided. This number should be adapted based on how dense the meshes' triangles density to get a reasonable amount of triangles per cell. For better visualization enable related fields in the QuantumEditorSettings asset's Collider gizmos section. This will affect the performance of both the broad phase and regular queries. Use the Task Profiler to analyse the performance and find the most suitable number for your game. More...
 
String ScenePath
 The Unity scene path is baked into the map for convenience. More...
 
Int32 SerializedTriangleDataUncompressedSize
 How big the serialized triangle data is in uncompressed form. More...
 
Boolean SerializeTrianglesMetadata = false
 If triangles metadata should be serialized (true) or recomputed (false) More...
 
PhysicsCommon.SortAxis SortingAxis = PhysicsCommon.SortAxis.Y
 The queries in a bucket are sorted according to their position in the sorting axis. More...
 
MapStaticCollider2D[] StaticColliders2D = Array.Empty<MapStaticCollider2D>()
 All static 2D colliders baked into this map. More...
 
MapStaticCollider3D[] StaticColliders3D = Array.Empty<MapStaticCollider3D>()
 All static 3D colliders baked into this map. More...
 
SortedDictionary< int, TriangleCCW[]> StaticColliders3DTriangles => null
 Obsolete More...
 
AssetRef< BinaryDataStaticColliders3DTrianglesData
 Binary 3D triangle data is saved on an addition Quantum asset. More...
 
List< PolygonColliderRuntimeDataStaticPolygonColliderData = new List<PolygonColliderRuntimeData>()
 The list of static 2D polygon collider runtime data. More...
 
Int32 TriangleMeshCellSize = -1
 Obsolete. Use SceneMeshCellSize instead for representing the cell size with an FP value. More...
 
AssetRef UserAsset
 An optional generic asset reference that the map can be associated with. More...
 
Int32 WorldSize = 256
 The physics scene size in the bucketing axis. The broad phase is clamped by a bounding box of all physics entries between -WorldSize/2 to WorldSize/2. It is therefore crucial to ensure the world is big enough to encompass all entities. If an entity is outside the world, it will cost you performance as it is added to either the first or last bucket. Everything outside the bounding box is considered to be at the world's edge, from the physics engine perspective, which will result in false collision candidates. In the non bucketing axis, the physics world is only limited by the value range of FP.UsableMin to FP.UsableMax. More...
 

Protected Member Functions

virtual void DeserializeRuntimeTriangles (Byte[] data, ref UnmanagedTriangleArray tris, SortedDictionary< int, MeshUnmanagedTrianglesRef > meshes, Native.Allocator allocator)
 Deserializes triangle data into runtime structures. More...
 
override void InitializeStaticTriangles (IResourceManager resourceManager, Native.Allocator allocator)
 Called when the map asset is loaded and the triangles are read into memory. More...
 
virtual void ReadRuntimeTriangles (ByteStream stream, SortedDictionary< int, MeshUnmanagedTrianglesRef > dict, Native.Allocator allocator, ref UnmanagedTriangleArray dest)
 Reads the runtime triangles from the given stream. More...
 
virtual Byte[] SerializeRuntimeTriangles (UnmanagedTriangleArray tris, SortedDictionary< int, MeshUnmanagedTrianglesRef > meshes)
 Serializes runtime triangle structures. More...
 
virtual void WriteRuntimeTriangles (ByteStream stream, UnmanagedTriangleArray source, SortedDictionary< int, MeshUnmanagedTrianglesRef > runtimeTriangles)
 Writes the runtime triangles to the given stream. More...
 
- Protected Member Functions inherited from Quantum.Map
virtual void ReadTrianglesFromBakeData (ByteStream stream, Native.Allocator allocator)
 Deserialize the static collider triangles data. More...
 
virtual void WriteTrianglesFromBakeData (ByteStream stream)
 Serialize the static collider triangles data. More...
 

Additional Inherited Members

- Properties inherited from Quantum.Map
Int32 WorldExtentX [get]
 The world extent in X-dimension that is covered by the Map.GridSizeX. Used by the navmesh system. More...
 
Int32 WorldExtentY [get]
 The world extent in Y-dimension that is covered by the Map.GridSizeY. Used by the navmesh system. More...
 
FPVector2 WorldOffset [get]
 The world offset. Used by the navmesh system. More...
 
Int32 WorldSizeX [get]
 The world size in X-dimension that is covered by the Map.GridSizeX. Used by the navmesh system. More...
 
Int32 WorldSizeY [get]
 The world size in Y-dimension that is covered by the Map.GridSizeY. Used by the navmesh system. More...
 

Detailed Description

Used to dynamically edit and manage mesh colliders and their triangles at runtime. This is particularly useful in games with procedurally generated content or user-generated levels, where the environment can change dynamically.

Member Function Documentation

◆ Loaded()

override void Quantum.DynamicMap.Loaded ( IResourceManager  resourceManager,
Native.Allocator  allocator 
)
inline

Called when the map asset is loaded.

Parameters
resourceManagerThe Quantum.IResourceManager for this asset.
allocatorThe Photon.Deterministic.Native.Allocator for this asset.

◆ EditMeshTriangles()

EditMeshScope Quantum.DynamicMap.EditMeshTriangles ( FrameBase  f,
int  meshColliderIndex 
)
inline

Edits the triangles of a mesh collider within a specific scope. When the scope is disposed, the changes are applied to the map.

Parameters
fThe current Frame. Must be Verified.
meshColliderIndexThe index of the mesh collider to edit.
Returns
An instance of the EditTriangleScope struct that represents the editing scope.

How to edit the triangles of a mesh collider:

using (var scope = dynamicMap.EditMeshTriangles(frame, colliderIndex)) {
TriangleCCW triangle = new TriangleCCW { A = v0, B = v1, C = v2 };
scope.SetTriangle(0, ref triangle);
}

◆ InitializeStaticTriangles()

override void Quantum.DynamicMap.InitializeStaticTriangles ( IResourceManager  resourceManager,
Native.Allocator  allocator 
)
inlineprotectedvirtual

Called when the map asset is loaded and the triangles are read into memory.

Parameters
resourceManagerThe resource manager for this asset.
allocatorThe allocator for this asset.

Reimplemented from Quantum.Map.

◆ WriteRuntimeTriangles()

virtual void Quantum.DynamicMap.WriteRuntimeTriangles ( ByteStream  stream,
UnmanagedTriangleArray  source,
SortedDictionary< int, MeshUnmanagedTrianglesRef runtimeTriangles 
)
inlineprotectedvirtual

Writes the runtime triangles to the given stream.

Parameters
streamThe ByteStream used to write the information.
sourceThe buffer of triangles to read.
runtimeTrianglesThe triangle dictionary lookup to read.

◆ SerializeRuntimeTriangles()

virtual Byte [] Quantum.DynamicMap.SerializeRuntimeTriangles ( UnmanagedTriangleArray  tris,
SortedDictionary< int, MeshUnmanagedTrianglesRef meshes 
)
inlineprotectedvirtual

Serializes runtime triangle structures.

Parameters
trisThe destination for the read triangles.
meshesThe dictionary from collider index to triangle references.
Returns
Raw byte array with the serialized data.

◆ ReadRuntimeTriangles()

virtual void Quantum.DynamicMap.ReadRuntimeTriangles ( ByteStream  stream,
SortedDictionary< int, MeshUnmanagedTrianglesRef dict,
Native.Allocator  allocator,
ref UnmanagedTriangleArray  dest 
)
inlineprotectedvirtual

Reads the runtime triangles from the given stream.

Parameters
streamThe stream to read from.
dictThe dictionary to read the triangles into.
allocatorThe allocator for this asset.
destThe destination for the read triangles.

◆ DeserializeRuntimeTriangles()

virtual void Quantum.DynamicMap.DeserializeRuntimeTriangles ( Byte[]  data,
ref UnmanagedTriangleArray  tris,
SortedDictionary< int, MeshUnmanagedTrianglesRef meshes,
Native.Allocator  allocator 
)
inlineprotectedvirtual

Deserializes triangle data into runtime structures.

Parameters
dataRaw serialized data.
trisThe destination for the read triangles.
meshesThe dictionary from collider index to triangle references.
allocatorThe allocator for this asset.

◆ ReserveMeshColliders()

bool Quantum.DynamicMap.ReserveMeshColliders ( FrameBase  f,
int  count,
int  capacity,
StaticColliderData staticData = null,
bool  resetPhysics = true 
)
inline

Pre-allocates space for a specified number of mesh colliders.

Parameters
fThe current Frame. Must be Verified.
countNumber of mesh colliders to reserve space for.
capacityTriangle capacity for each mesh collider.
staticDataOptional static data template for the reserved colliders.
resetPhysicsIf static physics data should be reset. Necessary after reserving all colliders.
Returns
true if reservation was successful, false otherwise.

How to reserve space for mesh colliders:

// Basic usage - reserve space for 10 mesh colliders with 100 triangles each
dynamicMap.ReserveMeshColliders(frame, 10, 100);

◆ AddMeshCollider()

int Quantum.DynamicMap.AddMeshCollider ( FrameBase  f,
IList< FPVector3 vertices,
IList< int >  indices = null,
int  additionalCapacity = 0,
StaticColliderData staticData = default,
bool  resetPhysics = true,
FPVector3 position = null,
FPQuaternion rotation = null,
AssetRef< PhysicsMaterial >?  material = null,
bool  smoothSphereCollisions = false 
)
inline

Adds a mesh collider to the map.

Parameters
fThe frame.
verticesThe vertices of the collider.
indicesThe indices (or triangles) of the collider.
positionThe position of the collider.
rotationThe rotation of the collider.
additionalCapacityExtra empty triangles to allocate.
staticDataThe static information for the created collider.
resetPhysicsIf the physics engine should be reset after adding.
materialThe physics material asset object. If null, it will use the default physics material.
smoothSphereCollisionsIf the mesh collider should have smooth sphere collisions.
Returns
The collider index of the created collider. -1 if it failed to create.

How to add a mesh collider to a dynamic map:

var vertices = new List<FPVector3> {
new FPVector3(0, 0, 0),
new FPVector3(1, 0, 0),
new FPVector3(0, 1, 0)
};
int meshColliderIndex = dynamicMap.AddMeshCollider(frame, vertices);
if(meshColliderIndex == -1) {
LogError?.Log("Failed to add mesh collider");
}
else {
Log.Info("Added mesh collider with index: " + meshColliderIndex);
}

◆ RemoveMeshCollider()

bool Quantum.DynamicMap.RemoveMeshCollider ( FrameBase  f,
int  meshColliderId,
bool  resetPhysics = true 
)
inline

Removes a mesh collider from the map.

Parameters
fThe frame.
meshColliderIdThe index of the collider to remove.
resetPhysicsIf the physics engine should be updated.
Returns
true if the removal was successful, false otherwise.

How to remove a mesh collider from a dynamic map:

if(dynamicMap.RemoveMeshCollider(frame, meshColliderIndex)) {
Log.Info("Removed mesh collider with index: " + meshColliderIndex);
}
else {
LogError?.Log("Failed to remove mesh collider with index: " + meshColliderIndex);
}

◆ AddCollider2D()

int Quantum.DynamicMap.AddCollider2D ( FrameBase  f,
MapStaticCollider2D  collider,
bool  resetPhysics = true 
)
inline

Adds a 2D collider to the map.

Parameters
fThe frame.
colliderThe collider to add.
resetPhysicsIf the physics engine should be updated.
Returns
The collider index of the created collider. -1 if it failed to create.

How to add a 2D collider to a dynamic map:

var collider = new MapStaticCollider2D {
ShapeType = Shape2DType.Circle,
CircleRadius = 1
};
int colliderIndex = dynamicMap.AddCollider2D(frame, collider);

◆ AddCollider3D()

int Quantum.DynamicMap.AddCollider3D ( FrameBase  f,
MapStaticCollider3D  collider,
bool  resetPhysics = true 
)
inline

Adds a 3D collider (non-mesh) to the map.

Parameters
fThe frame.
colliderThe collider to add.
resetPhysicsIf the physics engine should be updated.
Returns
The collider index of the created collider. -1 if it failed to create.

How to add a 3D collider to a dynamic map:

var collider = new MapStaticCollider3D {
ShapeType = Shape3DType.Box,
BoxExtents = new FPVector3(1, 1, 1)
}
int colliderIndex = dynamicMap.AddCollider3D(frame, collider);

◆ RemoveCollider3D()

bool Quantum.DynamicMap.RemoveCollider3D ( FrameBase  f,
int  colliderId,
bool  resetPhysics = true 
)
inline

Removes a 3D collider from the map.

Parameters
fThe frame.
colliderIdThe index of the collider to remove.
resetPhysicsIf the physics engine should be updated.
Returns
true if the removal was successful, false otherwise.

How to remove a 3D collider from a dynamic map:

if(dynamicMap.RemoveCollider3D(frame, colliderIndex)) {
Log.Info("Removed 3D collider with index: " + colliderIndex);
}
else {
LogError?.Log("Failed to remove 3D collider with index: " + colliderIndex);
}

◆ RemoveAllColliders3D()

void Quantum.DynamicMap.RemoveAllColliders3D ( FrameBase  f)
inline

Removes all 3D colliders.

Parameters
f

◆ RemoveAllColliders2D()

void Quantum.DynamicMap.RemoveAllColliders2D ( FrameBase  f)
inline

Removes all 2D colliders.

Parameters
f

◆ RemoveCollider2D()

bool Quantum.DynamicMap.RemoveCollider2D ( FrameBase  f,
int  colliderId,
bool  resetPhysics = true 
)
inline

Removes a 2D collider from the map.

Parameters
fThe frame.
colliderIdThe collider index to remove.
resetPhysicsIf the physics engine should be updated.
Returns
true if the removal was successful, false otherwise.

How to remove a 2D collider from a dynamic map:

if(dynamicMap.RemoveCollider2D(frame, colliderIndex)) {
Log.Info("Removed 2D collider with index: " + colliderIndex);
}
else {
LogError?.Log("Failed to remove 2D collider with index: " + colliderIndex);
}

◆ FromStaticMap< T >()

static T Quantum.DynamicMap.FromStaticMap< T > ( Map  map)
inlinestatic

Converts a static map to a dynamic map.

Parameters
mapThe map to copy.
Returns
The created dynamic version.

How to convert a static map to a dynamic map:

var dynamicMap = DynamicMap.FromStaticMap(f.Map);
Type Constraints
T :DynamicMap 

Member Data Documentation

◆ SourceMap

AssetRef<Map> Quantum.DynamicMap.SourceMap

The source map that was used to create this dynamic map.

◆ FreeTrianglePool

List<FreeTriangle> Quantum.DynamicMap.FreeTrianglePool = new List<FreeTriangle>()

Free triangles that can be used to store new triangles.

Quantum.Shape2DType
Shape2DType
Defines the geometry used by the Shape2D.
Definition: Physics2D.Type.Shape2D.cs:311
Quantum.Shape3DType
Shape3DType
Defines the geometry used by the Shape3D.
Definition: Physics3D.Type.Shape3D.cs:277