Actor System (Hero, 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/hero/Hero.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/WandOfWarding.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/Level.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/GameScene.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java

The Actor system is the foundational framework for all dynamic, "living" entities within the game. It manages the lifecycle, actions, and interactions of the player character (Hero), monsters (Mobs), and non-player characters (NPCs). The system is built on a hierarchical class structure and is driven by a turn-based, time-based action processing loop.

Every entity that can perform actions, from the Hero to the smallest rat, is an Actor. The Char class extends Actor to add common character-like features such as health, position, buffs, and combat mechanics. This is further specialized into Hero, Mob, and NPC classes, each with their own unique behaviors and properties. The entire system is designed to be extensible, allowing for a wide variety of character types with distinct abilities and AI.

Core Concepts

The Actor Class and Game Loop

The Actor class is the abstract base for all entities that participate in the game's turn-based loop. It defines the core timing and action-processing logic.

• Time and Cooldown: Each actor has a time variable that determines when its next action will occur. The game loop processes the actor with the lowest time value. Actions spend time, advancing the actor's time and creating a cooldown.
• Action Processing: The main game loop is managed by the static Actor.process() method. This method continuously finds the next actor to act, advances the global game time (now), and calls the actor's act() method.
• Action Priority: The actPriority field is used to resolve ties when multiple actors are scheduled to act at the same time. Actors with a higher priority (e.g., visual effects) act before those with a lower priority (e.g., buffs). The Hero has a priority of 0.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Actor.java:32-100, 192-251

The following diagram illustrates the actor processing loop.

Class Hierarchy

The actor system uses a clear inheritance model to build complexity. Actor is the base, Char adds combat and stats, and Hero, Mob, and NPC provide specialized implementations.

The Char Class

Char is an abstract class that represents any character in the game, including the hero, monsters, and NPCs. It builds upon Actor by adding attributes and methods for health, combat, buffs, and physical presence in the dungeon.

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

Core Attributes

Attribute	Type	Description
HP	int	Current health points.
HT	int	Maximum health points.
pos	int	The character's position on the level map (cell index).
alignment	enum Alignment	The character's relationship to the hero (ENEMY, NEUTRAL, ALLY).
buffs	LinkedHashSet<Buff>	A collection of active buffs and debuffs affecting the character.
properties	HashSet<Property>	A set of intrinsic properties, such as UNDEAD or FIERY.
paralysed	int	A counter for turns of paralysis.
rooted	boolean	If true, the character cannot move from its current position.
flying	boolean	If true, the character can move over chasms and some hazards.
invisible	int	A counter for turns of invisibility.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java:230-250, 1500-1502, 1530-1533

Combat System

The combat system is a complex interplay of stats, rolls, and special effects managed primarily within the Char class.

Attack Flow

An attack is initiated by the attack(Char enemy) method. The outcome is determined by a sequence of checks and calculations.

Hit Calculation

The static method hit(Char attacker, Char defender, ...) determines if an attack connects.

1. Infinite Accuracy/Evasion: Certain conditions, like an invisible attacker or a Monk's Focus buff, can grant infinite accuracy or evasion. Infinite evasion always wins.
2. Rolls: An acuRoll and defRoll are calculated based on the attacker's attackSkill and the defender's defenseSkill.
3. Modifiers: These rolls are then modified by various buffs (Bless, Hex, Daze), character properties, and challenge modes.
4. Comparison: The attack hits if acuRoll >= defRoll.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java:626-697

Damage Calculation & Application

If an attack hits, the damage() method is called on the defender.

1. Base Damage: Calculated via damageRoll().
2. Damage Multipliers: Various buffs like Berserk and Fury multiply the damage.
3. Defense Processing: The defender's defenseProc() is called, which can reduce damage via effects like Earthroot armor.
4. Damage Reduction (DR): The defender's drRoll() is subtracted from the damage.
5. Attack Processing: The attacker's attackProc() is called, which can add bonus effects.
6. Shielding: Damage is first applied to any active shields (ShieldBuff).
7. HP Reduction: Remaining damage is subtracted from the defender's HP.
8. Death: If HP drops to 0 or below, the character's die() method is called.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java:449-556, 920-1111

Properties, Resistances, and Immunities

Characters can have intrinsic Property values that grant them specific resistances and immunities to certain types of damage or effects.

Property	Resistances	Immunities
BOSS	Grim, GrimTrap, ScrollOfRetribution...	AllyBuff, Dread
MINIBOSS	(None)	AllyBuff, Dread
UNDEAD	(None)	(None)
DEMONIC	(None)	(None)
INORGANIC	(None)	Bleeding, ToxicGas, Poison
FIERY	WandOfFireblast...	Burning, Blazing
ICY	WandOfFrost...	Frost, Chill
ACIDIC	Corrosion	Ooze
ELECTRIC	WandOfLightning, Shocking...	(None)
LARGE	(None)	(None)
IMMOVABLE	(None)	Vertigo
STATIC	(None)	AllyBuff, Dread, Terror, Amok, Charm...

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/Char.java:1530-1569

The Hero Class

The Hero is a concrete implementation of Char that represents the player's character. It introduces player-specific mechanics like experience, leveling, talents, and direct action handling.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java

Player Actions

Player input is translated into HeroAction objects, which are processed in the Hero.act() method. This includes:

• HeroAction.Move: Moving to a destination.
• HeroAction.Attack: Attacking a target.
• HeroAction.PickUp: Picking up an item.
• HeroAction.Interact: Interacting with another character.

The handle(int cell) method is the entry point for most player-initiated actions, determining the correct HeroAction based on the target cell's contents.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java:1523-1610

Experience and Talents

• Leveling: The Hero gains experience (exp) by defeating enemies. When exp reaches maxExp(), the hero's lvl increases, and stats like HT, attackSkill, and defenseSkill are improved.
• Talents: Upon leveling up, the hero gains talent points, which can be spent in the talent tree to unlock or upgrade passive bonuses and abilities. The talents data structure stores the points allocated to each talent.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/actors/hero/Hero.java:1612-1677, 309-361

Mobs and NPCs

Mobs

Mob is the base class for all non-player, non-hero characters, primarily enemies.

• AI States: Mobs have a state machine that dictates their behavior (e.g., WANDERING, HUNTING, FLEEING).
• Spawning: Mobs are created and placed on the level by the Level class, often through a MobSpawner which ensures a steady stream of enemies. The createMob() method in Level is responsible for instantiating new mobs.
• Loot and Experience: Mobs typically drop loot and award xp to the hero upon death.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/levels/Level.java:613-649

NPCs

NPCs (Non-Player Characters) are a specialized type of Mob that are typically not hostile. They are defined by their interact() method, which allows for dialogue, quests, or other special actions.

A good example is the Ward created by the WandOfWarding. It is an ALLY character that is IMMOVABLE and has its own upgrade() and wandHeal() logic, separate from a standard mob.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/wands/WandOfWarding.java:152-309

Conclusion

The Actor system is the backbone of all character-based gameplay in Shattered Pixel Dungeon. Its hierarchical structure, from the abstract Actor to the specialized Hero and Mob classes, provides a robust and extensible foundation. The time-based action loop ensures fair, turn-based gameplay, while the detailed combat and buff systems allow for deep and complex character interactions. Understanding this system is key to understanding how entities live, fight, and die within the dungeon.