odinsea-elixir/JAVA_TODOS_PORT.md

# Java TODOs Analysis for Odinsea Elixir Port

**Analysis Date:** 2026-02-14  
**Java Source:** `/home/ra/lucid/src`  
**Elixir Target:** `/home/ra/odinsea-elixir`

---

## Summary

Total TODOs/FIXMEs/XXXs found in Java source: **87+**

After analysis, these fall into several categories:
1. **Critical Gameplay TODOs** - Missing functionality that affects core gameplay
2. **Version/Region-Specific TODOs** (TODO JUMP/GMS) - Code branches for different versions
3. **LEGEND TODOs** - High-level content/skills not fully implemented
4. **Low-Priority TODOs** - Nice-to-have features, optimizations, or minor fixes

---

## Critical TODOs Requiring Port to Elixir

### 1. Energy Charge Bar Decay (MapleCharacter.java:3034)

**Java Location:** `src/client/MapleCharacter.java:3034`
**Elixir Target:** `lib/odinsea/game/character.ex`

```java
// TODO: bar going down
if (energyLevel < 10000) {
    energyLevel += (echeff.getX() * targets);
    // ... energy charge handling
}
```

**Description:** The energy charge system for characters (like Aran) doesn't implement the energy bar decay over time. Currently energy only increases with attacks but doesn't decrease when not attacking.

**Implementation Needed:**
- Add energy charge decay timer in Character GenServer
- Decay energy when not attacking for X seconds
- Update client with energy bar changes

**Priority:** HIGH - Affects Aran and similar class gameplay

---

### 2. Party Quest Stats Tracking (MapleCharacter.java:7115)

**Java Location:** `src/client/MapleCharacter.java:7115`
**Elixir Target:** `lib/odinsea/game/character.ex` (party quest stats)

```java
// TODO: gvup, vic, lose, draw, VR
public boolean startPartyQuest(final int questid) {
    // ... quest initialization with stats
    updateInfoQuest(questid, "min=0;sec=0;date=0000-00-00;have=0;rank=F;try=0;cmp=0;CR=0;VR=0;gvup=0;vic=0;lose=0;draw=0");
}
```

**Description:** Party quest statistics (victories, losses, draws, VR rating) are stored but not calculated or updated.

**Implementation Needed:**
- Track PQ completion stats
- Calculate VR (Victory Rating)
- Implement gvup (give up?) tracking

**Priority:** MEDIUM - Nice for PQ ranking but not blocking

---

### 3. Player Movement Validation (PlayerHandler.java:1207)

**Java Location:** `src/handling/channel/handler/PlayerHandler.java:1207`
**Elixir Target:** `lib/odinsea/channel/handler/player.ex`

```java
if (res != null && c.getPlayer().getMap() != null) { // TODO more validation of input data
    if (packet.length() < 11 || packet.length() > 26) {
        return;
    }
```

**Description:** Movement packet validation is minimal. Need more comprehensive validation to prevent speed hacking and teleport exploits.

**Implementation Needed:**
- Validate movement distances against character speed stats
- Check for impossible position changes
- Validate foothold transitions

**Priority:** HIGH - Security/anti-cheat concern

**Note:** Elixir already has `Odinsea.Game.Movement` with validation - verify it covers these cases.

---

### 4. Party Invitation Pending Storage (PartyHandler.java:159)

**Java Location:** `src/handling/channel/handler/PartyHandler.java:159`
**Elixir Target:** `lib/odinsea/world/party.ex`

```java
// TODO store pending invitations and check against them
```

**Description:** Party invitations are not tracked, allowing potential exploits or duplicate invitations.

**Implementation Needed:**
- Store pending party invitations in ETS or GenServer state
- Validate accept/deny against pending list
- Add expiration for pending invites

**Priority:** MEDIUM - Prevents invitation spam/exploits

---

### 5. Summon Damage Validation (SummonHandler.java:226)

**Java Location:** `src/handling/channel/handler/SummonHandler.java:226`
**Elixir Target:** `lib/odinsea/channel/handler/summon.ex`

```java
// TODO : Check player's stat for damage checking.
```

**Description:** Summon damage lacks proper validation against player stats, allowing potential damage hacking.

**Implementation Needed:**
- Validate summon damage against calculated max damage
- Apply same anti-cheat checks as player attacks

**Priority:** HIGH - Security/anti-cheat concern

---

### 6. Multi-Summon BuffStat Handling (SummonHandler.java:260)

**Java Location:** `src/handling/channel/handler/SummonHandler.java:260`
**Elixir Target:** `lib/odinsea/channel/handler/summon.ex`

```java
//TODO: Multi Summoning, must do something about hack buffstat
```

**Description:** When a player has multiple summons, buff stat handling needs refinement to prevent exploits.

**Implementation Needed:**
- Track multiple active summons per player
- Handle buff stat stacking correctly

**Priority:** MEDIUM - Affects Mechanic and similar multi-summon classes

---

### 7. NPC Repair Price Calculation (NPCHandler.java:467)

**Java Location:** `src/handling/channel/handler/NPCHandler.java:467`
**Elixir Target:** `lib/odinsea/channel/handler/npc.ex`

```java
//TODO: need more data on calculating off client
```

**Description:** Equipment durability repair prices may not match client calculations.

**Implementation Needed:**
- Verify repair price formula matches client
- Ensure consistent pricing across server/client

**Priority:** LOW - Minor economic issue

---

### 8. Monster Revive Spawn Effect (MapleMap.java:1503)

**Java Location:** `src/server/maps/MapleMap.java:1503`
**Elixir Target:** `lib/odinsea/game/map.ex`

```java
c.sendPacket(MobPacket.spawnMonster(monster, monster.getStats().getSummonType() <= 1 ? -3 : monster.getStats().getSummonType(), oid)); // TODO effect
```

**Description:** Monster revive spawning doesn't show the proper spawn effect.

**Implementation Needed:**
- Send proper spawn effect packet when monsters revive
- Match visual effect to summon type

**Priority:** LOW - Visual polish only

---

### 9. Monster Party EXP Distribution (MapleMonster.java:1712)

**Java Location:** `src/server/life/MapleMonster.java:1712`
**Elixir Target:** `lib/odinsea/game/monster.ex`

```java
// TODO actually this causes wrong behaviour when the party changes between attacks
// only the last setup will get exp - but otherwise we'd have to store the full party
// constellation for every attack/everytime it changes, might be wanted/needed in the
// future but not now
```

**Description:** When party composition changes during combat, EXP distribution may be unfair.

**Implementation Needed:**
- Store party snapshot at time of attack
- Distribute EXP based on party composition at attack time, not kill time

**Priority:** MEDIUM - Fairness issue in party play

---

### 10. Speed Run Rank Calculation (MapleMap.java:3244)

**Java Location:** `src/server/maps/MapleMap.java:3244`
**Elixir Target:** `lib/odinsea/game/map.ex` (speed run feature)

```java
//TODO revamp
```

**Description:** Speed run ranking calculation needs improvement to properly track rankings.

**Implementation Needed:**
- Implement proper speed run leaderboard ranking
- Cache rank information efficiently

**Priority:** LOW - Feature enhancement

---

### 11. Anti-Cheat Attack Timing (CheatTracker.java:96,117)

**Java Location:** `src/client/anticheat/CheatTracker.java:96,117`
**Elixir Target:** `lib/odinsea/anticheat.ex` or `lib/odinsea/anticheat/monitor.ex`

```java
if (Server_ClientAtkTickDiff - STime_TC > 1000) { // 250 is the ping, TODO
// ...
if (STime_TC < AtkDelay) { // 250 is the ping, TODO
```

**Description:** Anti-cheat ping buffer is hardcoded at 250ms but should be dynamic per-player.

**Implementation Needed:**
- Track per-player average ping
- Adjust attack timing thresholds based on actual latency

**Priority:** MEDIUM - Reduces false positives for laggy players

---

### 12. Death Bug - Player Spawn (MapleStatEffect.java:1296)

**Java Location:** `src/server/MapleStatEffect.java:1296`
**Elixir Target:** `lib/odinsea/game/stat_effect.ex`

```java
applyto.setMoveAction(0); //TODO fix death bug, player doesnt spawn on other screen
```

**Description:** When a player is resurrected, they may not appear correctly on other players' screens.

**Implementation Needed:**
- Fix spawn broadcast packet for resurrected players
- Ensure proper visibility state sync

**Priority:** HIGH - Affects gameplay visibility

---

### 13. UnifiedDB Character Deletion Cleanup (UnifiedDB.java:168,177,188)

**Java Location:** `src/service/UnifiedDB.java:168,177,188`
**Elixir Target:** `lib/odinsea/database/context.ex`

```java
World.Guild.deleteGuildCharacter(nGuildId, nCharId); // TODO: Write method for this
pFamily.leaveFamily(nCharId); // TODO: Write method for this
pSidekick.eraseToDB(); // TODO: Write method for this
```

**Description:** Character deletion doesn't properly clean up guild, family, and sidekick associations.

**Implementation Needed:**
- Implement `delete_guild_character/2` in Guild service
- Implement `leave_family/2` for character deletion case
- Implement sidekick cleanup

**Priority:** HIGH - Data integrity issue

---

### 14. Mini-Game Score Formula (MapleMiniGame.java:276)

**Java Location:** `src/server/shops/MapleMiniGame.java:276`
**Elixir Target:** `lib/odinsea/game/mini_game.ex`

```java
public int getScore(MapleCharacter chr) {
    //TODO: Fix formula
    int score = 2000;
    // ... basic calculation
}
```

**Description:** Mini-game (Omok/Match Card) scoring formula is placeholder.

**Implementation Needed:**
- Implement proper ELO or ranking formula
- Balance win/loss/tie point values

**Priority:** LOW - Mini-games are side content

---

### 15. Mini-Game Record Points (MapleMiniGame.java:297)

**Java Location:** `src/server/shops/MapleMiniGame.java:297`
**Elixir Target:** `lib/odinsea/game/mini_game.ex`

```java
//TODO: record points
```

**Description:** Mini-game points are not persisted to database.

**Implementation Needed:**
- Add mini-game stats table
- Persist wins/losses/ties

**Priority:** LOW - Mini-games are side content

---

### 16. Family Splitting Logic (MapleFamily.java:690)

**Java Location:** `src/handling/world/family/MapleFamily.java:690`
**Elixir Target:** `lib/odinsea/world/family.ex`

```java
// TODO: MapleFamily: If errors persist, consider no handling family splitting
// inside the check of whether the family should be disbanded,
// and instead handle it in the caller after this function returns.
```

**Description:** Family splitting logic during disband check may cause issues.

**Implementation Needed:**
- Review family splitting algorithm
- Consider moving logic to caller

**Priority:** MEDIUM - Stability improvement

---

## Version-Specific TODOs (TODO JUMP / TODO LEGEND)

These TODOs indicate code that needs adjustment for different MapleStory versions (GMS vs SEA) or LEGEND content.

### TODO JUMP Items
- `ClientPacket.java:218` - Version-specific opcode handling
- `LoopbackPacket.java:345` - Version-specific packet format
- `MapleStatEffect.java:573,664,1014,1035,2323` - Version-specific skill behavior
- `PlayerHandler.java:365` - Version-specific movement
- `PartyHandler.java:31,235` - Version-specific party actions
- `InventoryHandler.java:1603` - Version-specific mount handling
- `MobPacket.java:399,420,474` - Version-specific monster packets
- `PacketHelper.java:371` - Version-specific character encoding
- `MaplePacketCreator.java:146,1243,1290,1330,1370,1941,2635,2652,5497,5511,5660` - Version-specific packets

### TODO LEGEND Items
- `ReactorActionManager.java:257` - Harvesting system (LEGEND profession system)
- `LoginInformationProvider.java:125` - LEGEND-specific login info
- `PlayerStats.java:947,2554` - LEGEND class skills (Demon Slayer, etc.)
- `MapleStatEffect.java:727,881` - Mercedes and other LEGEND skills

**Priority Assessment:** These should be deferred until base GMS v342 is fully stable.

---

## TODOs Already Implemented in Elixir

Based on PORT_PROGRESS.md, these Java TODOs appear to be already addressed:

1. **Movement System** - Elixir has comprehensive `Odinsea.Game.Movement` with validation
2. **Combat/Damage** - Elixir has `Odinsea.Game.DamageCalc` and `Odinsea.Game.AttackInfo`
3. **Drop System** - Elixir has `Odinsea.Game.DropSystem` fully implemented
4. **Quest System** - Elixir has complete quest implementation
5. **Skill System** - Elixir has `Odinsea.Game.Skill` and `Odinsea.Game.StatEffect`

---

## Port Priority Matrix

| Priority | Count | Description |
|----------|-------|-------------|
| **CRITICAL** | 4 | Data integrity, security exploits, game-breaking bugs |
| **HIGH** | 3 | Core gameplay features, anti-cheat, visibility |
| **MEDIUM** | 6 | Fairness, stability, feature completeness |
| **LOW** | 10+ | Visual polish, side content, optimizations |

---

## Recommended Implementation Order

### Phase 1: Critical Fixes
1. ✅ UnifiedDB character deletion cleanup (Guild/Family/Sidekick)
2. ✅ Death bug - player spawn on resurrection
3. ✅ Summon damage validation
4. ✅ Movement validation enhancement

### Phase 2: Core Features
5. ✅ Energy charge bar decay
6. ✅ Monster party EXP distribution fix
7. ✅ Party invitation tracking
8. ✅ Anti-cheat ping adjustment

### Phase 3: Polish
9. Mini-game improvements
10. Speed run ranking
11. Visual effects (monster spawn)
12. Version-specific content (TODO JUMP/LEGEND)

---

## Notes

- The Elixir port has excellent coverage of core systems (movement, combat, drops, quests)
- Most critical TODOs are around data integrity (character deletion) and anti-cheat
- Version-specific TODOs (TODO JUMP/LEGEND) should be deferred
- Several TODOs in Java are minor visual/economic issues that can be addressed later