Instance Module

Instance Module

The instance module builds on top of the bucket system to manage private gameplay spaces by type and key (for example house, lagerhalle, camper). It tracks members, optional moved entities, and player state, and can auto-destroy empty instances.

Naming & Identity

• Internal name format: instance:<type>:<key>
• Lookup tables are maintained by:
• name (string)
• bucketId (number)
• player source -> current instance name

Default Settings

If no custom settings are provided, these defaults are used:

{
    disableNpcs = true,
    lockEntity = true,
    moveToBucketOnJoin = true,
    teleportPosition = nil,
    leaveToBucket = 1,
    destroyWhenEmpty = true,
    emptyDestroyDelayMs = 0,
    bucketSettings = nil,
}

API

Query Functions

• cv.instance.get(typeOrName, key?) -> instance or nil
• With key: resolves by type + key
• Without key: resolves by full internal name
• cv.instance.getByBucketId(bucketId) -> instance or nil
• cv.instance.getPlayerInstance(source) -> instance or nil
• cv.instance.getAll() -> table of all live instances
• cv.instance.getAllStats() -> summarized instance table

Lifecycle Functions

• cv.instance.create(instanceType, key, settings?) -> instance or nil, error
• Creates backing bucket via cv.createBucket
• Returns existing instance if already created
• cv.instance.destroy(instanceType, key) -> true or false, error
• Forces all members to leave
• Deletes tracked entities
• Destroys backing bucket

Player Flow

• cv.instance.join(source, instanceType, key, settings?) -> true, instance or false, error
• Auto-creates instance if needed
• Leaves current different instance first
• Optionally moves player into instance bucket
• Updates player state:
  • instanceName
  • instanceType
  • instanceKey
  • instanceBucket
• Teleports player if configured
• cv.instance.leave(source, leaveToBucket?) -> true, instance or false, error
• Removes membership and state keys
• Moves player to configured fallback bucket (leaveToBucket, default 1)
• Triggers empty-instance destroy logic

Entity Function

• cv.instance.moveEntity(sourceOrEntity, entity?) -> true or false, error
• Accepts either:
  • (source, entity)
  • (entity, source)
• Moves entity to the player's current instance bucket
• Tracks moved entities for cleanup on destroy

Convenience Helpers

• cv.instance.joinHouse(source, houseId, settings?)
• cv.instance.joinLagerhalle(source, lagerhalleId, settings?)
• cv.instance.joinCamper(source, camperId, settings?)

Teleport Position Input

teleportPosition supports: - vector4 - vector3 (heading defaults to 0.0) - table forms: - keyed: { x = ..., y = ..., z = ..., w = ... } - indexed: { x, y, z, w } - heading alias: heading

Invalid or incomplete positions are ignored.

Events

Triggered server events: - cv_framework:instance:joined (source, instance) - cv_framework:instance:left (source, instance) - cv_framework:instance:destroyed (instance)

Automatic handlers: - On cv_framework:player:characterUnloaded: player leaves instance - On playerDropped: player leaves instance without forced bucket move - On resource stop: all live instances are destroyed

Auto-Destroy Behavior

Instances are destroyed when empty if destroyWhenEmpty = true.

Optional delayed destroy: - emptyDestroyDelayMs > 0 waits before final empty check and destroy

This avoids immediate deletion during short transitions.

Error Values

Common returned error strings: - instance_type_and_key_required - bucket_create_failed - invalid_source - join_bucket_failed - player_not_in_instance - instance_not_found - invalid_arguments

Example

-- Join or create a private house instance
local ok, instanceOrErr = cv.instance.joinHouse(source, houseId, {
    moveToBucketOnJoin = true,
    leaveToBucket = 1,
    teleportPosition = vector4(266.11, -1007.47, -101.0, 356.0),
    destroyWhenEmpty = true,
    emptyDestroyDelayMs = 5000,
})

if not ok then
    dprint("Failed to join house instance: " .. tostring(instanceOrErr))
    return
end

-- Move spawned object into same instance as player
cv.instance.moveEntity(source, spawnedObject)

Notes

• This module depends on the bucket module. Review buckets.md for lower-level bucket APIs.
• Prefer wrapper helpers (joinHouse, joinLagerhalle, joinCamper) where available for consistent naming.
• If you set moveToBucketOnJoin = false, you can still use instance state as a logical grouping without routing change.