Start repo, claude & kimi still vibing tho

2026-02-14 17:04:21 -07:00
commit f5b8aeb39d
54 changed files with 9466 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,174 @@
+# Odinsea Elixir
+
+An Elixir/OTP port of the Odinsea Java MapleStory private server.
+
+## Project Status
+
+**Current Phase:** Foundation Complete, Networking In Progress  
+**Overall Progress:** ~15%
+
+See [PORT_PROGRESS.md](./PORT_PROGRESS.md) for detailed progress tracking.
+
+## Architecture
+
+```
+Odinsea Elixir
+├── Login Server (port 8584)      - Authentication & character selection
+├── Channel Servers (ports 8585+) - Game world (multiple channels)
+├── Cash Shop (port 8605)         - Item purchasing
+├── World Services                - Cross-server state (parties, guilds)
+└── Database                      - MySQL/MariaDB via Ecto
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Elixir 1.17+
+- MySQL/MariaDB
+- Redis
+
+### Setup
+
+```bash
+# Install dependencies
+mix deps.get
+
+# Configure database (edit config/runtime.exs or use env vars)
+export ODINSEA_DB_HOST=localhost
+export ODINSEA_DB_NAME=odin_sea
+export ODINSEA_DB_USER=root
+export ODINSEA_DB_PASS=
+
+# Run database migrations
+mix ecto.setup
+
+# Start the server
+mix run --no-halt
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ODINSEA_NAME` | Luna | Server name |
+| `ODINSEA_HOST` | 127.0.0.1 | Server host |
+| `ODINSEA_LOGIN_PORT` | 8584 | Login server port |
+| `ODINSEA_CHANNEL_COUNT` | 2 | Number of game channels |
+| `ODINSEA_DB_HOST` | localhost | Database host |
+| `ODINSEA_DB_NAME` | odin_sea | Database name |
+| `ODINSEA_REDIS_HOST` | localhost | Redis host |
+
+## Project Structure
+
+```
+lib/odinsea/
+├── application.ex          # Main supervisor
+├── constants/              # Game constants
+│   ├── game.ex            # Game mechanics constants
+│   └── server.ex          # Protocol constants
+├── database/
+│   └── repo.ex            # Ecto repository
+├── login/                 # Login server
+│   ├── listener.ex        # TCP listener
+│   └── client.ex          # Client handler
+├── channel/               # Game channel servers
+│   ├── supervisor.ex      # Channel supervisor
+│   ├── server.ex          # Individual channel
+│   └── client.ex          # Channel client handler
+├── shop/                  # Cash shop server
+│   ├── listener.ex        # TCP listener
+│   └── client.ex          # Client handler
+├── world/                 # Cross-server services
+│   ├── supervisor.ex      # World supervisor
+│   ├── world.ex           # World state
+│   ├── party.ex           # Party management
+│   ├── guild.ex           # Guild management
+│   ├── family.ex          # Family management
+│   ├── expedition.ex      # Expedition management
+│   └── messenger.ex       # Messenger/chat
+└── net/                   # Networking
+    ├── opcodes.ex         # Packet opcodes
+    ├── hex.ex             # Hex utilities
+    └── packet/
+        ├── in.ex          # Packet decoder
+        └── out.ex         # Packet encoder
+```
+
+## Client Compatibility
+
+- **Version:** GMS v342
+- **Patch:** 1
+- **Revision:** 1
+
+## Key Differences from Java
+
+1. **Concurrency:** Elixir processes instead of Java threads
+2. **State:** GenServer/ETS instead of mutable fields
+3. **Networking:** gen_tcp instead of Netty
+4. **Database:** Ecto instead of raw JDBC
+5. **Hot Reloading:** Native Elixir code reloading
+
+## Development
+
+### Running Tests
+
+```bash
+mix test
+```
+
+### Code Quality
+
+```bash
+# Linting
+mix credo
+
+# Type checking
+mix dialyzer
+
+# Formatting
+mix format
+```
+
+### Packet Testing
+
+```elixir
+# Decode a packet
+packet = Odinsea.Net.Packet.In.new(<<0x01, 0x00, 0x05, 0x00>>)
+{opcode, packet} = Odinsea.Net.Packet.In.decode_short(packet)
+
+# Encode a packet
+packet = Odinsea.Net.Packet.Out.new(0x00)
+packet = Odinsea.Net.Packet.Out.encode_string(packet, "Hello")
+binary = Odinsea.Net.Packet.Out.to_binary(packet)
+```
+
+## Roadmap
+
+See [PORT_PROGRESS.md](./PORT_PROGRESS.md) for the complete roadmap.
+
+### Immediate Next Steps
+
+1. Implement AES encryption (`lib/odinsea/net/cipher/aes.ex`)
+2. Port login handlers (`lib/odinsea/login/handler.ex`)
+3. Create database schemas
+4. Implement login packet responses
+
+## Contributing
+
+This is a port of the Java Odinsea server. When implementing features:
+
+1. Reference the Java source in `/home/ra/lucid/src/`
+2. Follow Elixir/OTP best practices
+3. Update PORT_PROGRESS.md
+4. Add tests where applicable
+
+## License
+
+Same as the original Odinsea project.
+
+## Acknowledgments
+
+- Original Odinsea Java developers
+- MapleStory community
+- Elixir/OTP team