# PORTING.md — the port record Source: Java Swing bullet-hell ("EXALT", RotMG-style), ~6,650 lines across 79 classes. Target: `web/index.html` + `web/src` ES modules (grouped `core/ entities/ content/ presentation/`) + `web/assets`. No frameworks, no build step, Canvas 2D only. The Java source referenced throughout this file now lives under `legacy/java/`; its class names are unchanged. > **Status (July 2026): the web port is the canonical implementation.** The Java > original is frozen as a reference specimen — it receives no fixes or features. > Deliberate behavior changes (bug fixes) land in the JS only and are recorded in > this file by striking through the corresponding quirk entry (see #29 for the > pattern). **What this file is, now that only one side is maintained.** Mostly a historical record — but the quirks ledger below is not history, it is a **live safety rail**, and it is why this file stays. The port deliberately reproduces a long list of the original's odd behaviors, and without the ledger the only signal that a line is odd *on purpose* is that it looks wrong. Read it before "fixing" anything that looks like a bug. The class map, the timing model and the divergences list are reference: correct, useful for reading entity code beside its Java twin, but essentially append-only now. Two of them have already been partly overtaken — the Greek re-theme and the tier ladders broke the enemy and item classes' line-for-line correspondence with the Java, both recorded under Intentional divergences. **Design documentation for the game as it stands lives in [`ARCHITECTURE.md`](ARCHITECTURE.md)** — the arena and camera, the responsive canvas, dungeons and tier ladders, the enemy AI layer, the remaster presentation layer, and the performance rules. None of that was ported from anything, so none of it belongs here. A new subsystem documents itself there. ## Original bugs & quirks — the ledger Numbering is stable (code comments and issues reference it). This list used to be "preserved, not fixed" in its entirety; it is now a status ledger. Struck-through entries are retired: most were fixed in the web port under GitHub issues #3–#8 and #10–#15, two were retired earlier (7 reclassified as intended RotMG behavior, 29 an owner-approved typo fix that pre-dates the freeze and landed in both codebases), the remaster retired 26 plus the visual halves of 19 and 24, the circular-arena update retired 21, and 14 was retired on its own (one bullet, one enemy). Per the source-of-truth policy, the frozen Java reference keeps **every** original behavior, including the retired ones — a struck entry documents where the port now deliberately diverges from it. The remaining preserved entries (9, 16, the despawn half of 17, the logic half of 19, 20, 22, 25, 27, 28) stay preserved in the port on purpose; do not "fix" them. One entry is *narrowed* rather than struck: the enemy AI layer adds a lead offset on top of quirk 22's aim anchor without moving the anchor, so 22 stays in the do-not-fix list — see its entry. (The layers named as retiring entries — the remaster, the circular arena, the enemy AI — are documented in ARCHITECTURE.md.) 1. ~~Diagonal movement is √2 faster (per-axis speed, acknowledged in README).~~ **Fixed in the web port (issue #13)** — two non-opposing axes are normalized by √2/2; straight-line speed is unchanged. 2. ~~`Player.takeDamage`: when damage pierces defense, the popup shows the **full** damage value though `damage − defense` was applied.~~ **Fixed in the web port (issue #14)** — the popup now shows the amount actually subtracted. (The 20% minimum damage on absorbed hits is *not* a bug — it's RotMG's minimum-damage rule, intended.) 3. ~~`Enemy.takeDamage` minimum-damage branch computes the popup value from the **already-reduced** health (`takeDamageInt = health − damage*0.2` after the subtraction), so popups show a nonsense number.~~ **Fixed in the web port (issue #14)** — `takeDamageInt` is computed before health is mutated, in every branch. 4. ~~The player dies when a bullet's **raw** damage ≥ current health — defense is ignored in the lethality check (`Board.checkCollisions`).~~ **Fixed in the web port (issue #6)** — the hit always goes through `player.takeDamage` (defense + 20% minimum), and death triggers only when the mitigated health reaches ≤ 0. 5. ~~Level-up conditions are swapped: `maxMana < maximumMana` grants +10 max **health**; `maxHealth < maximumHealth` grants +15 max **mana**.~~ **Fixed in the web port (issue #7)** — each stat's growth now checks its own cap (only the conditions were swapped; the +10/+15 amounts stayed put). 6. ~~`Wizard.abilityCost` is captured once at spawn (60, from T1Spell) and never updated — a T3 spell deals 140 damage but still costs 60 mana.~~ **Fixed in the web port (issue #8)** — the cost is read live from the equipped ability on each SPACE press. 7. ~~The SPACE ability spawns its 12-bullet ring **at the mouse cursor position**, not at the player.~~ **Intended, per the owner**: this is the RotMG Wizard "spell bomb", which detonates its bolt burst at the cursor. Listed here only because it looks like a bug if you don't know the reference game. 8. ~~Item constructors are inconsistent about self-equipping: T2/T3 Atk/Def/Dex/Spd/Vit/Wis rings call `equipItem()` at construction, i.e. **their stats apply the moment the loot drops**, even if never picked up — and apply *again* when actually equipped (stats-over-cap exploit noted in the README). Hp/Mana rings and all T2/T3 staffs/spells/robes don't self-equip. All reproduced exactly per class.~~ **Fixed in the web port (issue #5)** — the 12 T2/T3 stat-ring `selfEquip` flags in `items.js` are now false, so equip/unequip applies stats exactly once each way; the frozen Java still self-equips them at construction. Self-equip survives only on the starting kit, which depends on it: that was tier 1 until the 0-13 tier ladder landed and is **tier 0** now — tier 1 became a real drop, and a dropped self-equipper is this exploit. (The frozen Java still self-equips its T1 gear, which there is only ever starting gear.) 9. `fireChanger` is first scheduled while `dexterity` is still 0 (400 ms period); equipping the starting robe reschedules it (328 ms in the Java; **345 ms in the web port**, whose starting kit is tier 0 and whose period formula diverged — see Intentional divergences) with delay 0, which also means any dex-changing equip grants an instant shot. The quirk itself — the instant shot on any dex-changing equip — is preserved. 10. ~~`ZombieKing.die()` (now `Hellhound`) lacks the `if (!visible) return` guard the other enemies have → two bullets killing it in the same tick grant 50 XP twice (loot is still dropped once).~~ **Fixed in the web port (issue #11)** — `die()` now opens with the same visibility guard as the other enemies; a second same-tick kill is a no-op. 11. ~~**Bes/Geb** (now Hyperion/Cronus): leaving the 1000 px range cancels only the aimed-shot timer; the 500 ms ring attack keeps firing forever once started, and each re-entry stacks an **additional** ring-attack task onto the same timer (rings fire faster and faster).~~ **Fixed in the web port (issue #4)** — range exit cancels `timer2` alongside `timer`, and range re-entry recreates it before scheduling (the same pattern as the issue #3 Nut fix). 12. ~~**Nut** (now Oceanus): leaving range cancels both timers, but re-entering schedules onto the cancelled timer → `IllegalStateException` **every tick**, which (on the Swing EDT) aborts the rest of that game update each tick — enemies/projectiles freeze while stacking a new 300 ms aimed-fire timer per tick. This is the most severe original bug.~~ **Fixed in the web port (issue #3)** — `timer2` is recreated on range re-entry, mirroring `timer`. The machinery that made this bug reproducible is deliberately unchanged: `GameTimer` still throws on schedule-after-cancel and the per-tick update still runs in the EDT-style try/catch — nothing in the port schedules on a cancelled timer anymore. 13. ~~Nut's (now Oceanus's) aimed volley aims its center bullet at `(0, playerY)` (`point2.getX()` typo — `point2` is always (0,0)).~~ **Fixed in the web port (issue #10)** — `fire` passes its own `point` parameter's x, so the center bullet is actually aimed at the player. (`fire2`'s unused parameter remains as-is.) 14. ~~A player bullet keeps testing (and damaging) further enemies in the same tick after its first hit — overlapping enemies are all damaged by one bullet.~~ **Fixed in the web port (July 2026)** — `checkCollisions` breaks out of the candidate loop on the first hit, so one bullet damages exactly one enemy; bullets are not piercing weapons in RotMG either. The same loop now also skips `!visible` candidates, so a bullet passes through a same-tick corpse instead of being spent on it (with the break in place, being consumed by something already dead would silently eat shots). 15. ~~Enemy bullets whose range expired this tick still collide with the player this tick (that loop never checks visibility); expired player bullets don't (that one does).~~ **Fixed in the web port (issue #15)** — the enemy-projectile loop now has the same `!visible → continue` guard as the player-projectile loop. 16. Every removal loop (`updateProjectiles`, `updateEnemies`, `updateBags`, damage lists) has the classic index-skip bug — the element after a removed one skips that pass. Replicated with equivalent single-pass compaction (skip-after-drop). 17. Loot bags despawn 10 s after creation — including bags you drop items into from your inventory (by design; the timers are untouched). ~~A full bag or full inventory silently destroys the item being moved.~~ **The silent-destruction half was fixed in the web port (issue #12)** — `Bag.add` now reports success, and a full destination leaves the item where it was (in the bag on pickup, in the inventory slot on drop). 18. ~~Health/mana pot pickup checks `<= 6`, so you can hold 7.~~ **Fixed in the web port (issue #15)** — all pickup checks are `< 6`; the counters cap at 6 and a 7th pot falls through to the inventory. 19. Damage popups live ~90 ms (10 ms tick, removed at `time > 8`) rising 1 px/tick. **Logic fully preserved** (the per-entity lists, their 10 ms timers and the index-skip removal still run, and tests read them); ~~their rendering~~ **the remaster no longer draws these lists** — floating combat text from `fx.js` (longer-lived, purely cosmetic) replaced them on screen. 20. Boss loot "T3 ring" branch always adds a guaranteed T3HpRing **plus** one random T3 ring (possibly a second T3HpRing). Same for the named monsters (was Medusa). 21. ~~Spawn ranges use the full 1920 px width, so enemies can spawn under the right-hand UI panel; the player is clamped to the 1620 px game area.~~ **Both halves retired by the circular-arena update.** The world is no longer the window: it is a disc of radius 1500 centred at (1650, 1650), the canvas is a camera onto it, and the UI panel is screen furniture that occupies no world space at all — so there is nothing to spawn "under". Spawns come through four cardinal gates on the rim, and the player is contained by a circular rule instead of the 1620×1080 rectangle. The frozen Java keeps the original behavior. Two incoherences went with it: escorts used to re-roll their position on every line (so a king's guard never actually clustered around it), and the zombie and named-monster branches disagreed about where the east edge was (`bX-300` = 1620 vs `bX` = 1920). 22. Wizard bullets originate at the sprite's **top-left**; enemy bullets originate at enemy center and aim at the player's **top-left**. **Preserved, and narrowed — not retired — by the enemy AI layer.** The top-left is still the *anchor* of every enemy shot, and `lead 0` (the default, and the only value the ported realm classes use below `AI_ROUND_GATE`) still resolves to `Math.round(player.x/y)` exactly as here. What an opted-in attack adds is a velocity *offset* on top of that anchor; the off-by-half-a-sprite bias this quirk describes is unchanged, so do not "fix" it by re-anchoring on the player's centre. 23. ~~The title screen (and README) say Right-click = shoot, Left-click = drop; the code does the opposite (Left = shoot/pick-up/equip, Right = drop). The port follows the **code**.~~ **Fixed in the web port (issue #15)** — the port's title-screen labels now read "Left Click = Use item / shoot" / "Right Click = Drop item", matching the implemented controls. The frozen Java title screen (and its actual controls, which were always Left = shoot) still shows the swapped text. 24. ~~Bag-panel slot 4 (second row, first cell) is missing its null check~~ (**fixed in the web port, issue #12** — slot 4 now has the same null-check shape as the other seven slots); ~~the inventory tooltip still draws slot 4's overflow line at y=200 instead of y=150~~ — **retired by the remaster**: the tooltip is now a wrapped card, so the slot-4 overflow line no longer exists (hover zones themselves are unchanged). 25. Holding SPACE retriggers the ability at the OS key-repeat rate in Java; the port likewise does not filter browser key-repeat. 26. ~~Game over has no restart (the Java app could only be closed); the port keeps that (reload the page).~~ **Retired by the remaster**: the game-over screen returns to the title on click, and the pause menu offers restart/quit. The Java-faithful post-death behavior underneath is intact — timers keep ticking on the dead board until the player actually leaves. 27. HP regen uses Java's compound-assignment truncation: `health += vit*0.15` truncates the *sum*; mana adds `(int)(wis*0.2)` each 500 ms. Reproduced with the same rounding. 28. `T1ManaRing`, `T1SpeedRing`, and `Enemy`'s string-less constructor are dead code (never instantiated / referenced only by dead paths). 29. ~~`T1Staff` declares `getInfwo()` (typo), so its real `getInfo()` is inherited and returns `""` — the starting staff's tooltip is blank.~~ **Fixed in both Java and JS per the owner** (minor typo, tooltip now shows "Attack: 20"). ## Class mapping | Java class | JS counterpart | Notes | |---|---|---| | `game.Application` | `web/src/main.js` | JFrame → canvas bootstrap, screen switching (title ↔ game). | | `game.TitleScreen` | `web/src/presentation/titlescreen.js` | JButtons → canvas-drawn buttons with hit tests. **Remaster:** fully redesigned visuals; the two button hit-rects and the control-listing strings are unchanged (tests assert both). | | `game.Board` | `web/src/core/board.js` | Main loop body, spawn/round logic, collision, all drawing. Swing `Timer(10ms)` → fixed-timestep update (see Timing). | | `game.MusicPlayer` | `web/src/presentation/audio.js` | `Clip.loop` → looping `