Actor values (actorValue) are key-value pairs that define an actor's properties, stats, and state. This reference documents all standard actor value keys defined in the engine.

Overview

Actor values provide:

Stats — Health, strength, speed, defence
Physical properties — Mass, height, luminosity
Movement — Jump power, flight, climbing
Combat — Tool size, reach, action timing
Identity — Name, race, species
State — Timers, counters, temporary flags
Special — Portal dictionary, ore dictionary, game mode

Accessing Actor Values

// Get value
val speed = actor.actorValue.getAsDouble(AVKey.SPEED)
val name = actor.actorValue.getAsString(AVKey.NAME)
val health = actor.actorValue.getAsDouble(AVKey.HEALTH)

// Set value
actor.actorValue[AVKey.SPEED] = 5.0
actor.actorValue[AVKey.NAME] = "Hero"
actor.actorValue[AVKey.HEALTH] = 100.0

// Check if exists
if (actor.actorValue.containsKey(AVKey.MAGIC)) {
    // Actor has magic
}

// Remove value
actor.actorValue.remove(AVKey.__ACTION_TIMER)

Movement and Physics

Speed

Key: AVKey.SPEED / AVKey.SPEEDBUFF

Type: Double

Unit: Pixels per frame

Description: Walking/running speed

Typical values:

Slow: 2-3 px/frame
Normal: 4-6 px/frame
Fast: 7-10 px/frame

actor.actorValue[AVKey.SPEED] = 5.0  // Base speed
actor.actorValue[AVKey.SPEEDBUFF] = 2.0  // Speed buff from equipment
// Effective speed = 5.0 + 2.0 = 7.0 px/frame

Acceleration

Key: AVKey.ACCEL / AVKey.ACCELBUFF

Type: Double

Unit: Pixels per frame squared

Description: Acceleration of movement (running, flying, driving)

actor.actorValue[AVKey.ACCEL] = 0.5  // Gradual acceleration

Jump Power

Key: AVKey.JUMPPOWER / AVKey.JUMPPOWERBUFF

Type: Double

Unit: Pixels per frame

Description: Initial velocity when jumping

Typical values:

Weak jump: 8-10 px/frame
Normal jump: 12-15 px/frame
High jump: 18-25 px/frame

actor.actorValue[AVKey.JUMPPOWER] = 15.0

Vertical Stride

Key: AVKey.VERTSTRIDE

Type: Double

Unit: Pixels

Description: Maximum height of a stair the actor can climb

Typical values:

Small creatures: 8-12 pixels
Humanoids: 16-20 pixels
Large creatures: 24-32 pixels

actor.actorValue[AVKey.VERTSTRIDE] = 18.0  // Can climb 18-pixel stairs

Air Jumping

Key: AVKey.AIRJUMPPOINT (max) / AVKey.AIRJUMPCOUNT (current)

Type: Int

Description: Number of air jumps allowed (double-jump, triple-jump, etc.)

Note: 0 is treated as 1 (one air jump allowed)

actor.actorValue[AVKey.AIRJUMPPOINT] = 2  // Can double-jump
actor.actorValue[AVKey.AIRJUMPCOUNT] = 0  // No jumps used yet

// When air jumping:
val current = actor.actorValue.getAsInt(AVKey.AIRJUMPCOUNT) ?: 0
val max = actor.actorValue.getAsInt(AVKey.AIRJUMPPOINT) ?: 0
if (current < max) {
    performAirJump()
    actor.actorValue[AVKey.AIRJUMPCOUNT] = current + 1
}

// Reset on landing:
actor.actorValue[AVKey.AIRJUMPCOUNT] = 0

Flight

Key: AVKey.FLIGHTPOINT (max) / AVKey.FLIGHTTIMER (current)

Type: Double

Unit: Seconds

Description: How long the actor can fly continuously

actor.actorValue[AVKey.FLIGHTPOINT] = 10.0  // Can fly for 10 seconds
actor.actorValue[AVKey.FLIGHTTIMER] = 0.0   // Not flying yet

// During flight:
val timer = actor.actorValue.getAsDouble(AVKey.FLIGHTTIMER) ?: 0.0
actor.actorValue[AVKey.FLIGHTTIMER] = timer + delta

// Check if out of flight time:
if (timer >= actor.actorValue.getAsDouble(AVKey.FLIGHTPOINT) ?: 0.0) {
    stopFlying()
}

Friction Multiplier

Key: AVKey.FRICTIONMULT

Type: Double

Description: Friction multiplier (only effective when noclip=true, e.g., camera actors)

Not meant for living creatures

actor.actorValue[AVKey.FRICTIONMULT] = 0.8  // Less friction

Drag Coefficient

Key: AVKey.DRAGCOEFF

Type: Double

Description: Air/water drag resistance

actor.actorValue[AVKey.DRAGCOEFF] = 0.5

Fall Dampen Multiplier

Key: AVKey.FALLDAMPENMULT

Type: Double

Description: Multiplier for fall damage reduction

actor.actorValue[AVKey.FALLDAMPENMULT] = 0.5  // 50% fall damage reduction

Physical Properties

Base Mass

Key: AVKey.BASEMASS

Type: Double

Unit: Kilograms

Description: Actor's body mass

Typical values:

Small animals: 5-20 kg
Humanoids: 50-100 kg
Large creatures: 150-500 kg

actor.actorValue[AVKey.BASEMASS] = 70.0  // 70 kg human

Base Height

Key: AVKey.BASEHEIGHT

Type: Double

Unit: Pixels

Description: Actor's standing height

actor.actorValue[AVKey.BASEHEIGHT] = 48.0  // 48 pixels tall

Scale

Key: AVKey.SCALE / AVKey.SCALEBUFF

Type: Double

Description: Size scale multiplier (aka PHYSIQUE)

actor.actorValue[AVKey.SCALE] = 1.0  // Normal size
actor.actorValue[AVKey.SCALE] = 1.5  // 150% size (larger, heavier)

Luminosity and Opacity

Luminosity

Keys:

AVKey.LUMR — Red channel
AVKey.LUMG — Green channel
AVKey.LUMB — Blue channel
AVKey.LUMA — UV channel

Type: Double

Unit: 0.0-1.0

Description: Light emitted by the actor

// Glowing actor (orange light)
actor.actorValue[AVKey.LUMR] = 0.8
actor.actorValue[AVKey.LUMG] = 0.4
actor.actorValue[AVKey.LUMB] = 0.1
actor.actorValue[AVKey.LUMA] = 0.0

Opacity

Keys:

AVKey.OPAR — Red channel opacity
AVKey.OPAG — Green channel opacity
AVKey.OPAB — Blue channel opacity
AVKey.OPAA — UV channel opacity

Type: Double

Unit: 0.0-1.0

Description: Light blocked by the actor

// Semi-transparent actor
actor.actorValue[AVKey.OPAR] = 0.5
actor.actorValue[AVKey.OPAG] = 0.5
actor.actorValue[AVKey.OPAB] = 0.5
actor.actorValue[AVKey.OPAA] = 1.0

Combat and Actions

Strength

Key: AVKey.STRENGTH / AVKey.STRENGTHBUFF

Type: Int

Default: 1000

Description: Physical strength

actor.actorValue[AVKey.STRENGTH] = 1000  // Base strength
actor.actorValue[AVKey.STRENGTHBUFF] = 200  // Buff from equipment
// Effective strength = 1200

Defence

Key: AVKey.DEFENCE / AVKey.DEFENCEBUFF

Type: Double

Unit: TBA

Description: Base defence point of the species

actor.actorValue[AVKey.DEFENCE] = 50.0
actor.actorValue[AVKey.DEFENCEBUFF] = 10.0

Armour Defence

Key: AVKey.ARMOURDEFENCE / AVKey.ARMOURDEFENCEBUFF

Type: Double

Unit: TBA

Description: Defence from equipped armour

actor.actorValue[AVKey.ARMOURDEFENCE] = 75.0  // From equipped armour

Reach

Key: AVKey.REACH / AVKey.REACHBUFF

Type: Double

Unit: Pixels

Description: Hand reach distance (affects gameplay as player)

Typical values:

Short reach: 32-48 pixels
Normal reach: 64-80 pixels
Long reach: 96-128 pixels

actor.actorValue[AVKey.REACH] = 72.0  // Can interact 72 pixels away

Tool Size

Key: AVKey.TOOLSIZE

Type: Double

Unit: Kilograms

Description: Size/weight of equipped tool

Affects:

Attack strength
Mining speed
Stamina drain

actor.actorValue[AVKey.TOOLSIZE] = 2.5  // 2.5 kg pickaxe

Action Interval

Key: AVKey.ACTION_INTERVAL

Type: Double

Unit: Seconds

Description: Time between actions (attack speed, mining speed)

actor.actorValue[AVKey.ACTION_INTERVAL] = 0.5  // 2 actions per second

Action Timer

Key: AVKey.__ACTION_TIMER

Type: Double

Unit: Milliseconds

Description: How long action button has been held, or NPC wait time

Internal state variable (prefixed with __)

// Track button hold time
val timer = actor.actorValue.getAsDouble(AVKey.__ACTION_TIMER) ?: 0.0
actor.actorValue[AVKey.__ACTION_TIMER] = timer + delta * 1000

// Reset on release
actor.actorValue.remove(AVKey.__ACTION_TIMER)

Encumbrance

Key: AVKey.ENCUMBRANCE

Type: Double

Description: Weight penalty from inventory

val totalWeight = inventory.getTotalWeight()
actor.actorValue[AVKey.ENCUMBRANCE] = totalWeight

Health and Magic

Health

Key: AVKey.HEALTH

Type: Double

Description: Current health points

actor.actorValue[AVKey.HEALTH] = 100.0

Magic

Key: AVKey.MAGIC

Type: Double

Description: Current magic/mana points

actor.actorValue[AVKey.MAGIC] = 50.0

Magic Regeneration Rate

Key: AVKey.MAGICREGENRATE / AVKey.MAGICREGENRATEBUFF

Type: Double

Unit: Points per second

Description: Magic regeneration rate

actor.actorValue[AVKey.MAGICREGENRATE] = 5.0  // Regenerate 5 magic/sec

Identity

Name

Key: AVKey.NAME

Type: String

Description: Actor's individual name

actor.actorValue[AVKey.NAME] = "Jarppi"

Race Name

Key: AVKey.RACENAME (singular) / AVKey.RACENAMEPLURAL (plural)

Type: String

Description: Species/race name

actor.actorValue[AVKey.RACENAME] = "Duudsoni"
actor.actorValue[AVKey.RACENAMEPLURAL] = "Duudsonit"

Intelligent

Key: AVKey.INTELLIGENT

Type: Boolean

Description: Whether the player can talk with this actor

actor.actorValue[AVKey.INTELLIGENT] = true  // Can be talked to

UUID

Key: AVKey.UUID

Type: String

Description: Unique identifier (for fixtures and special actors)

actor.actorValue[AVKey.UUID] = "550e8400-e29b-41d4-a716-446655440000"

Player-Specific

Game Mode

Key: AVKey.GAMEMODE

Type: String

Description: Current game mode (only for IngamePlayers)

Reserved values:

"survival" — Survival mode (future use)
"" (empty) — Creative mode

actor.actorValue[AVKey.GAMEMODE] = "survival"

Quick Slot Selection

Key: AVKey.__PLAYER_QUICKSLOTSEL

Type: Int

Description: Currently selected quick slot index

Internal state variable

actor.actorValue[AVKey.__PLAYER_QUICKSLOTSEL] = 3  // Slot 3 selected

Wire Cutter Selection

Key: AVKey.__PLAYER_WIRECUTTERSEL

Type: Int

Description: Wire cutter mode selection

Internal state variable

actor.actorValue[AVKey.__PLAYER_WIRECUTTERSEL] = 1

Historical Data

Born Time

Key: AVKey.__HISTORICAL_BORNTIME

Type: Long

Unit: TIME_T (world time seconds)

Description: When the actor was spawned

actor.actorValue[AVKey.__HISTORICAL_BORNTIME] = world.worldTime.TIME_T

Dead Time

Key: AVKey.__HISTORICAL_DEADTIME

Type: Long

Unit: TIME_T (world time seconds)

Description: When the actor died (-1 if alive)

actor.actorValue[AVKey.__HISTORICAL_DEADTIME] = -1L  // Alive
// On death:
actor.actorValue[AVKey.__HISTORICAL_DEADTIME] = world.worldTime.TIME_T

Special Dictionaries

World Portal Dictionary

Key: AVKey.WORLD_PORTAL_DICT

Type: String

Format: Comma-separated UUIDs (Ascii85-encoded, big endian)

Description: List of discovered world portals

// Example value:
"SIxM+kGlrjZgLx5Zeqz7,;:UIZ5Q=2WT35SgKpOp.,vvf'fNW3G<ROimy(Y;E<,-mdtr5|^RGOqr0x*T*lC,YABr1oQwErKG)pGC'gUG"

// Add portal:
val currentDict = actor.actorValue.getAsString(AVKey.WORLD_PORTAL_DICT) ?: ""
val newPortal = portalUUID.toAscii85()
actor.actorValue[AVKey.WORLD_PORTAL_DICT] = if (currentDict.isEmpty()) {
    newPortal
} else {
    "$currentDict,$newPortal"
}

Ore Dictionary

Key: AVKey.ORE_DICT

Type: String

Format: Comma-separated ItemIDs

Description: Ores the player has discovered

Note: Uses item IDs (item@basegame:128) not ore IDs (ores@basegame:1)

// Add discovered ore:
val oreDict = actor.actorValue.getAsString(AVKey.ORE_DICT) ?: ""
val newOre = "item@basegame:128"  // Copper ore item
if (!oreDict.contains(newOre)) {
    actor.actorValue[AVKey.ORE_DICT] = if (oreDict.isEmpty()) {
        newOre
    } else {
        "$oreDict,$newOre"
    }
}

// Check if ore discovered:
fun hasDiscoveredOre(actor: ActorWithBody, oreItemID: ItemID): Boolean {
    val oreDict = actor.actorValue.getAsString(AVKey.ORE_DICT) ?: ""
    return oreDict.split(',').contains(oreItemID)
}

Bare-Hand Actions

Bare-Hand Minimum Height

Key: AVKey.BAREHAND_MINHEIGHT

Type: Double

Description: Minimum height to enable bare-hand actions

actor.actorValue[AVKey.BAREHAND_MINHEIGHT] = 16.0

Bare-Hand Base Digging Size

Key: AVKey.BAREHAND_BASE_DIGSIZE

Type: Double

Description: Base digging size with bare hands

actor.actorValue[AVKey.BAREHAND_BASE_DIGSIZE] = 1.0  // 1x1 block

Buff System

Many keys have corresponding *BUFF keys for temporary bonuses:

// Base value + buff = effective value
val baseSpeed = actor.actorValue.getAsDouble(AVKey.SPEED) ?: 0.0
val speedBuff = actor.actorValue.getAsDouble(AVKey.SPEEDBUFF) ?: 0.0
val effectiveSpeed = baseSpeed + speedBuff

// Apply temporary speed boost:
actor.actorValue[AVKey.SPEEDBUFF] = 3.0  // +3 px/frame

// Remove buff:
actor.actorValue.remove(AVKey.SPEEDBUFF)

Buffable keys:

SPEED / SPEEDBUFF
ACCEL / ACCELBUFF
JUMPPOWER / JUMPPOWERBUFF
SCALE / SCALEBUFF
STRENGTH / STRENGTHBUFF
DEFENCE / DEFENCEBUFF
REACH / REACHBUFF
ARMOURDEFENCE / ARMOURDEFENCEBUFF
MAGICREGENRATE / MAGICREGENRATEBUFF

Naming Conventions

Regular keys — Lowercase, descriptive name
Buff keys — Base key + "buff" suffix
Internal state — Prefixed with __ (double underscore)
Historical data — Prefixed with __HISTORICAL_
Player-specific — Prefixed with __PLAYER_

Best Practises

Use AVKey constants — Never hardcode key strings
Check type before casting — Use getAsDouble(), getAsString(), etc.
Handle null values — Provide sensible defaults
Apply buffs additively — Base + Buff = Effective
Clean up temporary values — Remove timer/counter keys when done
Document custom keys — Add comments for module-specific keys
Namespace custom keys — Use "mymod:customkey" format
Serialise carefully — Not all keys should be saved
Use internal prefix — Mark transient state with __
Validate ranges — Clamp values to reasonable bounds

Common Pitfalls

Forgetting to check null — getAsDouble() returns null if missing
Not removing buffs — Buffs persist forever unless removed
Hardcoding key strings — Use AVKey constants
Wrong type casting — Check types before accessing
Modifying base stats directly — Use buffs for temporary changes
Not serialising important data — Historical data may be lost
Conflicting custom keys — Use unique namespaced keys
Assuming defaults — Not all actors have all keys
Not updating timers — Increment/decrement counters properly
Overwriting instead of adding — Buffs should add, not replace

Actor Values Reference

Overview

Accessing Actor Values

Movement and Physics

Speed

Acceleration

Jump Power

Vertical Stride

Air Jumping

Flight

Friction Multiplier

Drag Coefficient

Fall Dampen Multiplier

Physical Properties

Base Mass

Base Height

Scale

Luminosity and Opacity

Luminosity

Opacity

Combat and Actions

Strength

Defence

Armour Defence

Reach

Tool Size

Action Interval

Action Timer

Encumbrance

Health and Magic

Health

Magic

Magic Regeneration Rate

Identity

Name

Race Name

Intelligent

UUID

Player-Specific

Game Mode

Quick Slot Selection

Wire Cutter Selection

Historical Data

Born Time

Dead Time

Special Dictionaries

World Portal Dictionary

Ore Dictionary

Bare-Hand Actions

Bare-Hand Minimum Height

Bare-Hand Base Digging Size

Buff System

Naming Conventions

Best Practises

Common Pitfalls

See Also