Actors (Mobs & NPCs)

Relevant source files

The following files were used as context for generating this wiki page:

• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Actor.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/Mob.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/YogDzewa.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/DM300.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/npcs/Imp.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/CursedWand.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/WandOfWarding.java

The Actor system is the foundation for all dynamic entities within the game world, including the player (Hero), monsters (Mobs), and Non-Player Characters (NPCs). It manages the game's turn-based logic, character states, and interactions. Every entity that takes actions, has health, or participates in combat inherits from this system.

The core of the system is a clear inheritance hierarchy, starting with the abstract Actor class, which defines the basic turn-taking mechanism. The Char class extends Actor to add character-specific attributes like health, position, and combat logic. Finally, Hero and Mob classes extend Char to implement player-specific and monster-specific behaviors, respectively. NPCs are a specialized form of Mob.

Core Actor System

Actor Class

The Actor class is the most fundamental component of the character system. It provides the core turn-based mechanics for any entity that needs to perform actions over time in the game loop.

• Turn-Based Logic: Each Actor has a time property that tracks its cooldown. The main game loop in Actor.process() selects the actor with the lowest time value to act next.
• Action Execution: The act() method is an abstract method that must be implemented by subclasses to define the actor's behavior for a single turn.
• Action Priority: The actPriority field determines which actor goes first if multiple actors have the same time value. Higher priority actors act first. Default priorities are defined for major categories like HERO_PRIO, MOB_PRIO, and BUFF_PRIO.
• Global Management: A static HashSet<Actor> all tracks all active actors in the game, and a process() loop manages the turn order.

This diagram shows the main game loop for processing actor turns.

Char Class

Char is an abstract class that extends Actor and represents any character in the game that can engage in combat, move, and be affected by status effects (Buffs). It is the direct parent of Hero and Mob.

This diagram illustrates the inheritance structure of the core actor classes.

Key features of the Char class include:

• Core Attributes:
  • HP / HT: Current and maximum health points.
  • pos: The character's position on the level map.
  • alignment: An enum (ENEMY, NEUTRAL, ALLY) that defines its relationship to the hero.
  • buffs: A LinkedHashSet of Buff objects currently affecting the character.
• Combat Logic:
  • attack(Char enemy): Initiates an attack on another character. It calculates hit chance and damage.
  • damage(int dmg, Object src): Applies damage to the character, processes resistances, immunities, and shielding, and triggers die() if HP drops to 0 or below.
  • hit(Char attacker, Char defender, ...): A static method that determines if an attack lands based on attacker's accuracy and defender's evasion stats.
• Properties: A HashSet<Property> defines intrinsic traits like BOSS, UNDEAD, INORGANIC, etc. These properties grant automatic resistances or immunities.

Combat Sequence

The following diagram shows the sequence of a standard character attack.

Character Properties

The Property enum defines special traits that affect a character's immunities and resistances.

Property	Immunities	Resistances
BOSS	AllyBuff, Dread	Grim, GrimTrap, ScrollOfRetribution, ScrollOfPsionicBlast
MINIBOSS	AllyBuff, Dread	None
UNDEAD	None	None
DEMONIC	None	None
INORGANIC	Bleeding, ToxicGas, Poison	None
FIERY	Burning, Blazing	WandOfFireblast, Elemental.FireElemental
ICY	Frost, Chill	WandOfFrost, Elemental.FrostElemental
ACIDIC	Ooze	Corrosion
ELECTRIC	None	WandOfLightning, Shocking, Potential, Electricity, ShockingDart, Elemental.ShockElemental
LARGE	None	None
IMMOVABLE	Vertigo	None
STATIC	AllyBuff, Dread, Terror, Amok, Charm, Sleep, Paralysis, Frost, Chill, Slow, Speed	None

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java:1280-1317

Mobs (Monsters)

Mobs are characters controlled by AI. The Mob class extends Char and introduces an AI state machine to govern behavior.

AI State Machine

A Mob's behavior is determined by its current AiState. The act() method delegates to the current state's act() method.

State	Description
SLEEPING	The mob is inactive. It can be awoken by nearby hostiles, with the chance depending on the hostile's stealth and distance.
WANDERING	The mob moves to random destinations on the level until it detects an enemy.
HUNTING	The mob has a target and will actively try to move towards and attack it.
FLEEING	The mob will attempt to move away from its target. This is typically triggered by Terror or Dread buffs.
PASSIVE	The mob takes no action. Used for mobs that are inert or have special activation conditions.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/Mob.java:100-106, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/Mob.java:449-627

This diagram illustrates the transitions between different AI states.

Mob Spawning

Mobs are spawned on a level through two primary mechanisms:

1. Initial Creation: When a level is first generated, Level.createMobs() is called. This method populates the level with a set number of mobs from a rotation specific to the dungeon depth.
2. Respawner: The MobSpawner actor periodically spawns new mobs. The cooldown for respawning is defined in Level.respawnCooldown() and is influenced by factors like whether the Amulet has been obtained and the current level's "feeling". Spawned mobs are placed at a random valid cell outside the hero's field of view.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/Level.java:547-592, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/MobSpawner.java

Example Boss: Yog-Dzewa

Yog-Dzewa is the final boss and demonstrates a complex, multi-phase AI. Its behavior is managed within its act() method, controlled by a phase variable.

• Phase 0 (Inactive): The boss is inactive until the hero comes into view.
• Phase 1 (Active): The boss becomes active, starts its ability and summon cooldowns, and attacks with its laser ability.
• Phases 2-4 (Fist Phases): When Yog-Dzewa's health reaches certain thresholds (multiples of 300 HP), it becomes invulnerable and summons one or two YogFist minions. It remains invulnerable until all fists are defeated.
• Phase 5 (Final Phase): After the last fist is defeated, the boss becomes vulnerable again, summons a final wave of minions, and attacks more aggressively with reduced cooldowns until defeated.

This flowchart shows the progression of the Yog-Dzewa boss fight.

NPCs (Non-Player Characters)

NPCs are a specialized type of Mob that are generally not hostile and serve specific functions, such as providing quests or services. They often have the IMMOVABLE property and a custom interact() method.

Example NPC: Imp

The Imp is a quest-giver found in the Dwarven City.

• Properties: It is IMMOVABLE and has INFINITE_EVASION, meaning it cannot be moved or damaged.
• Interaction: Its interact(Char c) method is overridden to handle quest logic.
  • If the quest has not been given, it initiates the quest.
  • If the quest is active, it checks for the required number of DwarfToken items in the hero's inventory and opens the shop window (WndImp) if the condition is met.
• Quest Management: A static inner class, Imp.Quest, manages the state of the quest, including whether it's been given, completed, and what the reward is. This state is stored and restored globally.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/mobs/npcs/Imp.java:29-100

Special Allies

Some mobs are designed to be allies to the player, often summoned by items or hero abilities.

• WandOfWarding.Ward: A stationary ally summoned by the Wand of Warding. It can be upgraded by zapping it again with the wand. At tier 4, it becomes a WardSentry and gains health, damage reduction, and a ranged attack. It has a limited number of zaps before it expires.
• Cursed Wand Summons: A cursed wand can have a variety of effects, including summoning a Sheep or a GoldenMimic. A "positive" cursed effect can even make the summoned mimic enthralled (permanently allied).

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/WandOfWarding.java:143-261, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/CursedWand.java:499-521, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/CursedWand.java:700-738

Conclusion

The actor system in Shattered Pixel Dungeon is a robust, hierarchical framework that powers all living entities in the game. From the fundamental turn-based Actor to the complex, state-driven AI of Mobs and bosses, the system provides a flexible and extensible foundation for character behavior. The use of properties, alignments, and a rich buff system allows for a wide variety of interactions and combat dynamics, making it a central pillar of the game's mechanics.