# Eclipse Core Client<\/p>\n
A client-side companion mod for Cobblemon that enables advanced multi-player battle formats, including cooperative raid battles.<\/p>\n
## Features<\/p>\n
– **Multi-Player Raid Support** – Enables 1-4 player cooperative battles against a single powerful opponent
\n– **Targeting System Override** – Allows proper target selection in non-standard battle formats
\n– **Battle Side Organization** – Correctly displays allies and enemies in the battle UI
\n– **Doubles\/Triples Gimmick Fix** – Prevents using the same battle gimmick (Mega Evolution, Terastallization, Z-Moves, Dynamax) multiple times in a single turn<\/p>\n
## Requirements<\/p>\n
– Minecraft 1.21.1
\n– Fabric Loader 0.16.5+
\n– Fabric API
\n– Fabric Language Kotlin
\n– Cobblemon 1.7.1+<\/p>\n
## Installation<\/p>\n
1. Download and place in your client’s `mods` folder
\n2. This mod is **client-side only** – it communicates with compatible server mods via custom packets<\/p>\n
## For Mod Developers<\/p>\n
Interested in creating your own raid or multi-battle mod for Cobblemon? Here’s what you need to know:<\/p>\n
### The Core Challenge<\/p>\n
Cobblemon’s battle system is designed for 1v1 and 2v2 formats. To create raids (4v1, 3v1, etc.), you need to solve several problems:<\/p>\n
1. **Battle Creation** – How do you start a battle with 4 players on one side?
\n2. **Targeting** – How do players target the single boss when adjacency rules say they can’t?
\n3. **Side Display** – How do you show allies correctly when the client expects standard formats?
\n4. **Showdown Compatibility** – How do you make Showdown accept non-standard team configurations?<\/p>\n
### Server-Side: Starting Multi-Player Battles<\/p>\n
Look at Cobblemon’s `BattleBuilder` and `BattleRegistry`. Key classes:
\n– `BattleBuilder` – Creates battles with actors and format
\n– `BattleActor` – Represents a participant (player or NPC)
\n– `BattleFormat` – Defines the battle rules (singles, doubles, etc.)
\n– `PokemonBattle` – The active battle instance<\/p>\n
For raids, you’ll need multiple `BattleActor` instances on one side. Study how Cobblemon handles doubles – it’s the foundation for multi-player.<\/p>\n
### The Showdown Layer<\/p>\n
Cobblemon uses Pokemon Showdown for battle logic. Battles are created via:
\n“`
\nBattleRegistry.startBattle(format, side1Actors, side2Actors)
\n“`<\/p>\n
Showdown receives team data as “pack strings” – compact representations of Pokemon. The format is documented in Showdown’s source. Key insight: Showdown’s `fPokemon` format includes species, level, moves, ability, etc.<\/p>\n
For raid bosses, consider:
\n– How would you give a Pokemon more effective HP?
\n– How would you let one Pokemon take hits from multiple attackers?
\n– What happens when Showdown calculates damage against a “scaled” target?<\/p>\n
### Client-Side: The Targeting Problem<\/p>\n
In standard doubles, Pokemon can only target adjacent slots. In a 4v1 raid, ALL players need to target the single boss.<\/p>\n
The client uses `ActiveClientBattlePokemon.getAdjacent()` to determine valid targets. This method checks positions and returns valid targets based on battle format.<\/p>\n
Eclipse Core Client solves this by:
\n– Intercepting target requests
\n– Overriding adjacency calculations for raid formats
\n– Communicating raid configuration via custom packets<\/p>\n
### Packet Communication<\/p>\n
Fabric networking allows custom packets between server and client:
\n“`kotlin
\n\/\/ Server-side: Register and send
\nPayloadTypeRegistry.playS2C().register(…)
\nServerPlayNetworking.send(player, payload)<\/p>\n
\/\/ Client-side: Register receiver
\nClientPlayNetworking.registerGlobalReceiver(…)
\n“`<\/p>\n
Your packet should tell the client:
\n– Is this a raid battle?
\n– How many players are participating?
\n– Which side is the boss on?<\/p>\n
The client needs this info BEFORE the battle UI renders to correctly organize sides.<\/p>\n
### Showdown Modifications (Advanced)<\/p>\n
Cobblemon extracts Showdown to `.\/showdown\/`. The JavaScript files in `sim\/` control battle mechanics:
\n– `battle.js` – Main battle loop and turn handling
\n– `pokemon.js` – Pokemon state, HP, PP management
\n– `side.js` – Side management and slot handling
\n– `battle-actions.js` – Move execution and damage<\/p>\n
For raid mechanics, you might need to modify how:
\n– Damage is calculated against the boss
\n– PP is tracked (infinite PP for bosses?)
\n– Multi-target moves resolve
\n– The boss takes actions against multiple targets<\/p>\n
Mixin into `GraalShowdownUnbundler.attemptUnbundle()` to patch files after extraction.<\/p>\n
### Mixin Targets Reference<\/p>\n
**Client-side** (for targeting\/display fixes):
\n– `ActiveClientBattlePokemon` – Target selection and adjacency
\n– `BattleMoveSelection` – Move selection UI
\n– `ClientBattle` – Side organization<\/p>\n
**Server-side** (for battle creation):
\n– `BattleBuilder` – Battle initialization
\n– `BattleActor` – Actor behavior
\n– `NPCBattleActor` – NPC-specific logic<\/p>\n
### Getting Started<\/p>\n
1. Create a basic server mod that starts a doubles battle
\n2. Add a third player to one side – observe what breaks
\n3. Study the errors to understand the constraints
\n4. Implement fixes one layer at a time (Showdown \u2192 Server \u2192 Client)<\/p>\n
The journey from “doubles work” to “4v1 raids work” will teach you everything about Cobblemon’s battle system.<\/p>\n
—<\/p>\n
## Eclipse Packet Protocol<\/p>\n
Want your server mod to work with Eclipse Core Client? Implement these packets:<\/p>\n
### Packet 1: Client Handshake (Client \u2192 Server)<\/p>\n
**Channel:** `eclipse_raids:client_handshake`<\/p>\n
When a player with Eclipse Core Client joins your server, they send this packet.<\/p>\n
| Field | Type | Description |
\n|——-|——|————-|
\n| protocolVersion | Int | Client protocol version (currently `2`) |<\/p>\n
**Kotlin Codec:**
\n“`kotlin
\nbuf.writeInt(protocolVersion)
\n\/\/ Read: buf.readInt()
\n“`<\/p>\n
Use this to track which players have the client mod installed. Block raid participation for players without it.<\/p>\n
### Packet 2: Handshake Acknowledgment (Server \u2192 Client)<\/p>\n
**Channel:** `eclipse_raids:handshake_ack`<\/p>\n
Send this back to confirm the client is recognized.<\/p>\n
| Field | Type | Description |
\n|——-|——|————-|
\n| raidsEnabled | Boolean | Whether raids are enabled on this server |
\n| message | String | Status message (shown in client logs) |<\/p>\n
**Kotlin Codec:**
\n“`kotlin
\nbuf.writeBoolean(raidsEnabled)
\nbuf.writeString(message)
\n“`<\/p>\n
### Packet 3: Raid Side Configuration (Server \u2192 Client)<\/p>\n
**Channel:** `eclipse_raids:raid_side_config`<\/p>\n
**This is the critical packet.** Send this after starting a raid battle to tell the client which actors are allies vs enemies.<\/p>\n
| Field | Type | Description | **Kotlin Codec:** \/\/ Read ### Showdown ID Convention<\/p>\n Showdown assigns IDs based on battle position: In a 4v1 raid: ### When to Send RaidSideConfig<\/p>\n **Timing is critical.** Send the packet:<\/p>\n 1. **After** `BattleRegistry.startBattle()` returns Recommended: Send immediately, then send again after 3 seconds (60 ticks) as a safety net in case the client wasn’t ready.<\/p>\n “`kotlin \/\/ Safety net – resend after 3 seconds ### What the Client Does<\/p>\n When Eclipse Core Client receives `RaidSideConfigPayload`:<\/p>\n 1. Finds the active `ClientBattle` matching `battleId` This fixes: ### Payload Classes (Fabric 1.21.1)<\/p>\n “`kotlin \/\/ Handle incoming handshakes ### Without This Client Mod<\/p>\n If a player doesn’t have Eclipse Core Client: Block raid participation for players without the client mod by checking your handshake tracking.<\/p>\n ## Compatibility<\/p>\n This mod is designed to work with server-side raid mods that implement the Eclipse packet protocol. Without a compatible server mod, it functions as a passive gimmick fix for doubles\/triples battles.<\/p>\n ## Support<\/p>\n This mod is provided as-is for use with compatible Eclipse server mods.<\/p>\n","protected":false},"excerpt":{"rendered":" This project’s core functionality is to enable double battle gimmicks in cobblemon clients, it servers other purposes as well to enable 4v1 raids on servers that create their own mods. Additional functionality will eventually be added.<\/p>\n","protected":false},"featured_media":43322,"template":"","meta":{"_minecraft_slug":"eclipse-core-client","_minecraft_project_id":"NUbIlDfd","_minecraft_author":"spg","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":2344,"_minecraft_follows":4,"_minecraft_client_side":"required","_minecraft_server_side":"unsupported","_minecraft_storage_type":"zip","_minecraft_archive_name":"eclipse-core-client.zip","_minecraft_size_bytes":20018624,"_minecraft_version_count":7,"_minecraft_updated_at":"2026-05-15T21:08:15.926847Z","_minecraft_date_created":"2026-01-07T02:19:46.928575Z","_minecraft_date_modified":"2026-04-05T05:16:47.690447Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/eclipse-core-client","_minecraft_icon_attachment_id":43322,"_minecraft_imported_at":"2026-06-03T13:45:22+00:00","_minecraft_import_hash":"aca53dbd22a412024a32366513ba38cd","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,89,873],"mod_loader":[99],"minecraft_version":[37],"class_list":["post-61423","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-game-mechanics","mod_category-library","mod_loader-fabric","minecraft_version-1-21-1"],"yoast_head":"\n
\n|——-|——|————-|
\n| battleId | UUID | The battle’s UUID from `PokemonBattle.battleId` |
\n| allyShowdownIds | List
\n| enemyShowdownIds | List
\n“`kotlin
\n\/\/ Write
\nbuf.writeUuid(battleId)
\nbuf.writeInt(allyShowdownIds.size)
\nallyShowdownIds.forEach { buf.writeString(it) }
\nbuf.writeInt(enemyShowdownIds.size)
\nenemyShowdownIds.forEach { buf.writeString(it) }<\/p>\n
\nval battleId = buf.readUuid()
\nval allyCount = buf.readInt()
\nval allyIds = (0 until allyCount).map { buf.readString() }
\nval enemyCount = buf.readInt()
\nval enemyIds = (0 until enemyCount).map { buf.readString() }
\n“`<\/p>\n
\n– **p1, p3, p5, p7** – Odd numbers for one side (use for players)
\n– **p2, p4, p6, p8** – Even numbers for opposite side (use for boss)<\/p>\n
\n– Player 1 \u2192 p1
\n– Player 2 \u2192 p3
\n– Player 3 \u2192 p5
\n– Player 4 \u2192 p7
\n– Boss \u2192 p2<\/p>\n
\n2. **Before** the player opens the battle UI (they have ~1-2 seconds)<\/p>\n
\n\/\/ Immediately after battle starts
\nfor (player in players) {
\n ServerPlayNetworking.send(player, RaidSideConfigPayload(battle.battleId, allyIds, enemyIds))
\n}<\/p>\n
\nScheduler.schedule(60) {
\n for (player in players) {
\n ServerPlayNetworking.send(player, RaidSideConfigPayload(battle.battleId, allyIds, enemyIds))
\n }
\n}
\n“`<\/p>\n
\n2. Collects all `ClientBattleActor` from both sides
\n3. Reorganizes them: allies \u2192 `side1`, enemies \u2192 `side2`
\n4. Sets `isInRaidBattle = true` (enables targeting override)<\/p>\n
\n– Pokemon appearing on wrong visual side
\n– Players unable to target the boss (adjacency override kicks in)<\/p>\n
\n\/\/ Register in your mod initializer
\nPayloadTypeRegistry.playC2S().register(ClientHandshakePayload.ID, ClientHandshakePayload.CODEC)
\nPayloadTypeRegistry.playS2C().register(HandshakeAckPayload.ID, HandshakeAckPayload.CODEC)
\nPayloadTypeRegistry.playS2C().register(RaidSideConfigPayload.ID, RaidSideConfigPayload.CODEC)<\/p>\n
\nServerPlayNetworking.registerGlobalReceiver(ClientHandshakePayload.ID) { payload, context ->
\n val player = context.player()
\n \/\/ Track that this player has the client mod
\n \/\/ Send acknowledgment back
\n}
\n“`<\/p>\n
\n– Normal 1v1 and 2v2 battles work fine
\n– Raid battles will have broken targeting (players can’t select the boss)
\n– Pokemon may appear on wrong sides visually<\/p>\n