Tower Instances

Room generation (rooms.yml)

InstanceService#generateRoomSequence builds the sequence position by position, from 0 up to the highest generation.max across all configured rooms:

1. At each position, filter to rooms that (a) haven't been used yet in this sequence and (b) have that position within [min, max].

2. Pick one at random, weighted by chance, via a RandomCollection.

3. If no room is eligible for a position, instance creation fails with an IllegalStateException.

Each room is used at most once per instance — a room's blueprint never repeats within the same run. Position 0 is always the lobby room in the shipped config (min: 0, max: 0, chance: 100), so it's the only room eligible there.

Mob scaling (mobs.yml)

Both modifiers stack multiplicatively (each is its own AttributeModifier, both MULTIPLY_SCALAR_1) and are applied on EntitySpawnEvent for every living entity spawned in a tower world, then the entity's health is set back to its (now higher) max health. Mobs spawn a few at a time on a repeating scheduler (starting at 1, incrementing every other tick) at the room's MOB position components, cycling through the available spawn points; the boss room additionally spawns at its dedicated BOSS position component. Once every mob for the room has spawned, the room moves to RoomPhase.COMBAT.

Room phases

Each RoomInstance tracks a RoomPhase:

InstanceService#changePhase fires RoomStateChangeEvent before applying each transition, then branches on the new phase:

• On REWARDS: the lobby room skips straight to COMPLETE; a shop room spawns shop offers and also skips to COMPLETE; otherwise the room's rewardType decides whether artifacts spawn (staying in REWARDS until every participant claims one, then ArtifactService#claimArtifact advances the room straight to COMPLETE — not END_REWARDS, which is only used for the death/end-of-run reward chest, see Instance lifecycle) or coins spawn (advancing straight to COMPLETE). A room with no reward and no next room ends the instance (EndCause.COMPLETED); a room with no reward but more rooms ahead just advances to COMPLETE.

• On COMPLETE: RoomService#openDoors opens the room's doors. See Doors below.

Rooms with a mob set that spawns zero mobs (or a shop room) skip straight from SPAWNING to REWARDS.

Doors

A cleared room's COMPLETE phase opens every DOOR component in its blueprint, each tagged with a RoomRewardType describing what the next room offers if the party walks through that door:

• If the next room's blueprint type is LOBBY, its door's reward type is forced to NONE.

• If it's SHOP, forced to SHOP; if BOSS, forced to BOSS.

• Otherwise, doors are assigned ARTIFACTS or COINS, trying to give each door a different type first before falling back to a fully random pick once both have been used once.

Walking into a door's area (PlayerMoveEvent, block-change granularity) fires RoomDoorEnterEvent; if not cancelled, the next room's rewardType is set from the door's type and the instance advances to it (InstanceService#nextRoom), which re-runs room setup for the new room.

Instance lifecycle

An instance ends (InstanceService#endInstance, EndCause) when:

If the ending room is the instance's last room and the cause is COMPLETED, or the cause is DEATH, the instance transitions to RoomPhase.END_REWARDS and spawns reward chests instead of destroying immediately — see Loot, Shop & Rewards. Otherwise (any other COMPLETED, or PLAYER_QUIT) the instance is destroyed after a 300-tick delay: participants are teleported to fallback-group, the instance is removed from the repository, and its world is unloaded and deleted.

On disable, AstralTower#onDisable calls InstanceService#deleteAllInstances() to tear down every active instance before the plugin shuts down.

Custom events

The paper module fires the following custom Bukkit events. All extend AbstractEvent (com.astralrealms.core.paper.model.event) and can be listened to with @EventHandler as usual.