{"id":43549680,"url":"https://github.com/nmeylan/rust-ro","last_synced_at":"2026-02-03T19:13:54.631Z","repository":{"id":43928468,"uuid":"398837546","full_name":"nmeylan/rust-ro","owner":"nmeylan","description":"A Ragnarok online server implementation from scratch, for fun","archived":false,"fork":false,"pushed_at":"2026-01-24T15:22:37.000Z","size":78583,"stargazers_count":168,"open_issues_count":20,"forks_count":24,"subscribers_count":11,"default_branch":"master","last_synced_at":"2026-01-24T23:56:44.057Z","etag":null,"topics":["game","mmorpg","ragnarok","ragnarok-online","rust"],"latest_commit_sha":null,"homepage":"https://discord.gg/AJkR8mhdFJ","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmeylan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-08-22T15:47:06.000Z","updated_at":"2026-01-24T14:42:19.000Z","dependencies_parsed_at":"2024-01-22T19:07:57.628Z","dependency_job_id":"6edd65c2-40d2-4546-9ffe-9c5590469c63","html_url":"https://github.com/nmeylan/rust-ro","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nmeylan/rust-ro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeylan%2Frust-ro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeylan%2Frust-ro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeylan%2Frust-ro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeylan%2Frust-ro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmeylan","download_url":"https://codeload.github.com/nmeylan/rust-ro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeylan%2Frust-ro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29054197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T15:43:47.601Z","status":"ssl_error","status_checked_at":"2026-02-03T15:43:46.709Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game","mmorpg","ragnarok","ragnarok-online","rust"],"created_at":"2026-02-03T19:12:16.094Z","updated_at":"2026-02-03T19:13:51.901Z","avatar_url":"https://github.com/nmeylan.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![build](https://github.com/nmeylan/rust-ro/actions/workflows/rust.yml/badge.svg)\n\n[Discord](https://discord.gg/AJkR8mhdFJ)\n\n[Rust ro 3 years journey blog post](https://nmeylan.ch/blog/rust-ro-3-years-after/)\n# Welcome to rust-ro!\n**rust-ro** is a Ragnarok MMO Server implementation written in Rust. \n\nThis project does **not** aim to compete with [herculesWS](https://github.com/HerculesWS/Hercules) or [rathena](https://github.com/rathena/rathena).\n\nAlthough the architecture and technical decision of this project are very different than **rathena** or **hercules**, both projects are still a source of inspiration and remain source of truth for game behavior.\n\nIn addition, this project kept some concept of existing implementations: for example this project support same scripting language for NPC meaning that existing scripts should work on this implementation and use the same database structure than rathena and some naming convention were kept.\n\nArchitecture and technical decision are documented [here](/doc/adr)\n\n## 1. Ambition\n\nThe project started on August 2021 with the ambition to being able to connect on the server and navigate across maps to see monsters.\n\nToday February 2023 a lot of features have been added, at the end of readme. My ultimate goal would be to have a fully playable implementation for **PRE-RE**, supporting packet version **20120307**.\n\nI am working on this project for **fun** and also to provide a more accessible way than existing implementation to understand how Ragnarok game works for educational purpose. Each feature is covered with tests to provide internal documentation.\n\n## 2. About Packet Version\nThe packets [parser, builder and serializer](https://github.com/nmeylan/rust-ro/tree/master/lib/packets/src) are all taking packet version as parameter. The [packet db](https://github.com/nmeylan/rust-ro/blob/master/tools/packets/packets_db) also support condition around packet [attributes](https://github.com/nmeylan/rust-ro/blob/master/tools/packets/packets_db#L112) and [packet id](https://github.com/nmeylan/rust-ro/blob/master/tools/packets/packets_db#L423)\n\nAlthough I mentioned above wanting to fully support packet version **20120307**, this implementation can support any packet version, it is just I am testing exclusively with a [robrowser client](https://github.com/MrAntares/roBrowserLegacy) using this packet version and thus i am implementing only packet in this version.\n\n## 3. Currently Working\nBelow issues are under active development\n- [Skills issue](https://github.com/nmeylan/rust-ro/issues/11) - [Offensive skills progress](/doc/progress/offensive-skills-progress.md)\n- [Status and bonus issue](https://github.com/nmeylan/rust-ro/issues/29) - [Stats for each job level progress](/doc/progress/stats-for-each-job-level_progress.md) [Stats for each items](/doc/progress/stats-for-each-items_progress.md) [Stats for each cards](/doc/progress/stats-for-each-card_progress.md)\n\n\n## 4. Implementation details\n\nTo understand what is going on at this project, check the [architectures notes](doc/Architecture.md).\n\n### 4.1 Project files structure\n- `lib`: contains either, `proc-macro`, `reusable structure`, `generated code`\n  - `lib/packets`: Structure for packets generated by `tools/packets` from `tools/packets_db` file\n  - `lib/models`: Plain old data structure to be reused in multiple modules\n  - `lib/configuration`: Structure for configuration with serde deserializer implementation\n  - `lib/skills`: Generated structures for skills from `configuration` and also manually implemented skills methods\n- `server`: server core\n  - `server/proxy`: A proxy implementation to be use between a client and an emulator (rathena or hercules) in order to capture packets\n  - `server/repository`: data access layer of the server, any access to dabase is written from this layer\n  - `server/server`: global event loop, map instance event loop, persistence event loop\n  - `server/server/boot`: any method require in order to boostrap server state (script loader, maploader, mob spawn...)\n  - `server/server/model`: Plain old non-reusable data structure (queue, cells, etc..)\n  - `server/server/request_handler`: controller layer, any packet receive from client pass to a controller first\n  - `server/server/script`: interface between server and script virtual machine, provides hook implementation of the virtual machine\n  - `server/server/service`: any logic of the game is implemented in this layer\n  - `server/server/state`: Data structure containing game state (character session, character state, mob state)\n  -  `server/util`: Any utility methods\n- `tools`: code generator\n  - `tools/map-cache`: generate map cache from map files\n  - `tools/packets`: generate packets structure from database file\n  - `tools/skills`: generate skills structure from configuration file \n  - `tools/stat-calc`: A javascript/html stat calculator, cleaned up to better understand stats and combat calculation. Also added feature to generate test fixtures, to validate our implementation  \n\n\n## 5. Setup \n\nHere's a list of **pre-requisites** to run rust-ro:\n\n* Docker OR PostgreSQL 12+ directly on your machine \n* Rust - nighly build\n\n### 5.1 Config\n\nFirst, make a copy from `config.template.json` to `config.json`:\n\n```shell\ncd rust-ro\ncp config.template.json config.json\n```\nInside this JSON, you will find **database related variables**, **game related variables** (exp_rate, drop_rate etc) as well.\n\n\n\n### 5.2 Database\n\nThe entire database structure was based on **rAthena** but instead of using MySQL, we decided to go with PostgreSQL. There's minor modifications so far but until we mapped some **constraints**. \n\nThe choice to use Postgresql instead of MySQL was mainly motivated because I know better how to operate Postgresql than MySQL, and know better how Postgresql (mvcc) works internally.\nIn addition past years Postgresql gained more traction than MySQL and its open source model \n\n#### 5.2.1 Setup Database - Using Docker\n\nIf you already have **Docker** installed in your machine, we prepared a **docker-compose.yml** with all configs ready for your ragnarok server.\n\nGo to */docker* and run:\n```shell\ndocker-compose up -d\n```\n\nThe first time, along with postgresql `initdb` is run, our custom script `init.sh` will be execute, it will create `ragnarok` database and create `ragnarok` user using `postgres` user. Then it will create ragnarok table using `ragnarok` user.\n\nIt comes with a default player account with following credentials: `admin/qwertz`\n\n#### 5.2.1 Setup Database - From binary\n\nIf you have PostgreSQL installed in your machine, you will need to log-in into PSQL and create the user, dabase and give the necessary privilege for it:\n\n```shell\nsudo -u postgres psql\n```\n\nRun the queries below: \n\n```sql \nCREATE USER ragnarok WITH PASSWORD 'ragnarok';\nCREATE DATABASE ragnarok;\nGRANT ALL PRIVILEGES ON DATABASE ragnarok TO ragnarok;\nALTER DATABASE ragnarok OWNER TO ragnarok;\n```\n\nAfter that, exit pgsql and import our `/rust-ro/db/pg.sql` via cli with:\n\n```shell\n sudo -u postgres psql -U ragnarok ragnarok \u003c db/pg.sql\n```\n\n### 5.3 Running the Server\n\nAfter we have everyting set-up (binaries and database), we should run server binary to turn on **rust-ro**.\n\nTo run the `server` binary, you will need a `ENV` variable called `DATABASE_PASSWORD` together with your command:\n\n```shell\nDATABASE_PASSWORD=ragnarok cargo run --package server --bin server\n```\n\nIf everything goes right, you should receive something like this output:\n\n```\n2024-02-11 13:45:53.695168 +01:00 [main] [INFO]: Compiled 0 item scripts compiled, skipped 2492 item scripts compilation (already compiled) in 73ms\n2024-02-11 13:45:54.976721 +01:00 [main] [INFO]: load 39 scripts in 1104ms\n2024-02-11 13:45:55.110070 +01:00 [tokio-runtime-worker] [WARN]: Not able to load boot script: pre-re/warps/other/sign.txt, due to No such file or directory (os error 2)\n2024-02-11 13:45:55.113409 +01:00 [main] [INFO]: load 2782 warps in 6ms\n2024-02-11 13:45:55.134622 +01:00 [\u003cunnamed\u003e] [INFO]: load 3392 mob spawns in 19ms\n2024-02-11 13:45:55.152271 +01:00 [main] [INFO]: Loaded 897 map-cache in 44ms\n2024-02-11 13:45:55.378476 +01:00 [main] [INFO]: Executed and cached 1601 item scripts, skipped 891 item scripts (requiring runtime data) in 226ms\n2024-02-11 13:45:55.388987 +01:00 [\u003cunnamed\u003e] [INFO]: Start proxy for map proxy, 6124:5121\n2024-02-11 13:45:55.389135 +01:00 [\u003cunnamed\u003e] [INFO]: Start proxy for Char proxy, 6123:6121\n2024-02-11 13:45:55.389212 +01:00 [main] [WARN]: Visual debugger has been enable in configuration, but feature has not been compiled. Please consider enabling \"visual-debugger\" feature.\n2024-02-11 13:45:55.389241 +01:00 [main] [INFO]: Server started in 2347ms\n2024-02-11 13:45:55.389292 +01:00 [main] [INFO]: Server listen on 0.0.0.0:6901\n```\n\n### 5.4 [Dev] Running tools \n\nSo far, we have a few executables being compiled together with the project:\n\n- **maps-tool:** Generate mapcache files from client data: `cargo run --package tools --bin maps-tool`\n- **packets-tool:** Generate packet struct from packetdb: `cargo run --package tools --bin packets-tool`\n- **skills-struct-generator:** Generate skills struct from skills configuration files: `cargo run --package tools --bin skills-struct-generator`\n\n\n#### 5.5 Running the Game\n![Desktop Screenshot with Development Environment using RoBrowserLegacy](.github/images/robrowser-dev.png)\n\nThe goal of the project is to run all packages from **packetver 20120307**, we decided to use [roBrowserLegacy](https://github.com/MrAntares/roBrowserLegacy). \n\nIf you have interest to contribute in a client with packetver 20120307, open a new issue and let's make it happen!\n\n#### 5.6 Running the Stat calculator/test case editor\nThe stat calculator is a highly _customized*_  fork of from https://web.archive.org/web/20090319055622/http://rode.doddlercon.com/db/calc/index.php\n\n_*Customized_ :\n- Code has been de-obfuscated to make it comprehensive\n- Code has been reorganize so it at can work on both browser and node environment\n- Customize calculation behavior in order to get sub calculation output (e.g: get just the weapon attack before applying some modifier)\n- Build a test case editor to generate and edit fixtures for unit and integration tests\n\nThe idea behind reusing stat calculator is to validate implementation of battle and status calculation.\n\nOutput of stat calculator may be false and in this case we will check result against hercules or rathena.\n\n```\ncd tools/stat-calc\nnpm run dev\n```\n![Stat calculator](.github/images/stat-calc.png)\n\n## 6. Developer Notes\n\n- All packets for account 2000000 are handle by this project.\n- All packets for any other account are proxied (and display in console) to hercules or rathena.\n- clientinfo.xml to be changed to target port 6901\n\nIn proxy mode:\n- login, char, map server to be running using default ports (6900, 6121, 6122)\n\n\n## 7. Progress Showcase (Compilation)\nA compilation of progress made so far, **click on streamable video below**\n\n[![Compilation of features so far](https://res.cloudinary.com/marcomontalbano/image/upload/v1678527790/video_to_markdown/images/streamable--jiapub-c05b58ac6eb4c4700831b2b3070cd403.jpg)](https://streamable.com/jiapub \"Compilation of features so far\")\n\n[![Compilation of features so far](https://res.cloudinary.com/marcomontalbano/image/upload/v1678527859/video_to_markdown/images/streamable--ofni1d-c05b58ac6eb4c4700831b2b3070cd403.jpg)](https://streamable.com/ofni1d \"Compilation of features so far\")\n\n### 7.1 Integration of the VM (showing instance and class(npc) variable)\n\nhttps://user-images.githubusercontent.com/1909074/178155321-d3eeb4b8-32ed-4901-bbfe-b101b1a5a56d.mp4\n\n### 7.2 Visual debugger\n![visual-debugger](doc/img/visual_debugger.PNG)\n![visual-debugger](doc/img/stats_debugger.PNG)\nDebug server state with a UI\n\n### 7.3 Warps\n![warps](doc/img/warp_spawn.PNG)\n![warps](doc/img/warp.PNG)\n\n### 7.4 Mobs\n![mobs](doc/img/mob_spawn.PNG)\n\n### 7.5 Proxied packets\n![packets](doc/img/packet_analyzer.PNG)\n\n\n## 8. What has been done? ✔️\n\nSome list of features that was developed so far: \n\n### 8.1 Tools\n- packet structure generator from [packet db](https://github.com/nmeylan/rust-ro/blob/master/tools/packets/packets_db)\n- packet parser generator\n- map cache generator\n- character generator\n- stat simulator and test case generator\n- skills structure generator\n### 8.2 Server\n- proxy login, char and map request to hercules/rathena login, char and map servers\n- packet debug\n- login\n- char server features(create char, delete char, join game)\n- move character in a loaded map, synchronized with client side movement (no lag, or teleportation, movement is smooth)\n- character position calculation (implementation of client side path finding)\n- debug log in in-game chat \n- parse scripts (only warps and mobs at the moment)\n- warp (change map, reset states)\n- display scripts client side (only warps and mobs at the moment)\n- visual debugger\n- map instances (map are lazily loaded, an instance is created when a player join an non initialized map)\n- mob spawn\n- mob death\n- item drop from mob\n- base/job exp reward\n- base/job level up\n- skill tree\n- skill point allocation\n- status point allocation\n- atcommand: @go, @warp\n- mob move\n- NPC scripts (partially: see https://github.com/nmeylan/rust-ro/issues/3) via [rathena script lang interpreter](https://github.com/nmeylan/rathena-script-lang-interpreter)\n- basis for inventory management\n- basis for skills\n- basis for consumable item usage\n- basis for player attacking mob\n- mob drops item on death\n\n## 9. Contribution\nThis project is currently _half-open*_ to contribution. The reason is that all basis have not been put in place already and there are many thing to design yet.\n\nHowever if you are motivated and want to contribute you can take a look to the [contribution guide](https://github.com/nmeylan/rust-ro/blob/master/Contributing.md)\n\n_* contribution can be made under certain condition_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeylan%2Frust-ro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmeylan%2Frust-ro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeylan%2Frust-ro/lists"}