Project

Contributing to L2jMobius

How code gets into the project, what 'contributor access' means, and the rules that keep the codebase clean.

The release rhythm:

   Three public releases per year     ─► everyone gets the code,
                                        no questions, no fee.

   Active development branch          ─► visible to contributors
                                        and supporters in between
                                        releases.

   Contributor access                 ─► earned by submitting code
                                        improvements. Not bought.

   Supporter access                   ─► donations help cover
                                        hosting and tooling. Donors
                                        get temporary early access
                                        as a thank-you.

   "Always eventually free"           ─► every line lands in a
                                        public release.

This is the same model used by Patreon-funded open projects,
WordPress plugin authors and Blender add-on developers.

What "contributing" actually looks like

L2jMobius is small enough that there is no formal pull-request process, contributions come in as patches, posts, or direct submissions through the forum. The bar is not "do you have commit rights"; the bar is "does the change improve the project".

What lands quickly

  • Bug fixes with a clear repro and the smallest possible diff.
  • XML corrections - an item with the wrong stats, a skill with a wrong effect, a spawn in the wrong place. These are the single largest category of change in the project.
  • New handlers following the patterns on the Patterns page.
  • Quest scripts placed correctly under dist/data/scripts/quests/.
  • Chronicle ports - a fix that already landed in one chronicle, hand-ported (not symlinked) to another, with the diff reviewed against the destination's surrounding code.

What gets bounced

  • Wrapping that hides complexity. See the Coding Style page, signatures and control flow stay on one line.
  • Over-custom code that complicates server logic or runtime. Bespoke abstractions, deep inheritance, extra layers "for flexibility", or new background threads added without a clear need. Mobius keeps the hot paths simple and the runtime predictable; complexity has to pay for itself.
  • Refactors with no behaviour change sent without a reason. Mobius optimises for readability, not for theoretical purity; gratuitous restructuring is churn.
  • "Improvements" that quietly change game balance. If the change alters drop rates, XP, or skill effects, it goes through configuration or XML, not through Java logic.
  • Anything with provenance you cannot defend. See below.

The provenance rule

Never paste code whose origin you cannot vouch for. Not from a decompiler. Not from a leaked retail server. Not from another emulator that may itself have used leaked sources. The whole legal foundation of the project (see Gitlab README.md and MIT Transition) rests on the codebase being clean-room. One careless paste contaminates the file, the contributor, and potentially the chronicle.

If you are unsure, document the source you used and ask before submitting. "I wrote this from a packet capture I made myself" is fine. "I copied this from a forum post" is not, unless that forum post itself documents a clean origin.

The development model in plain terms

The three tiers

Public release  ─► three times a year. Anyone can download
                  and use it under MIT (or GPLv3 for legacy
                  files still in flight, see the file headers).

Contributor     ─► you have submitted accepted work. You get
                  access to the active development branch in
                  between public releases. No fee.

Supporter       ─► you donated to help cover hosting and
                  tooling. You get temporary early access as a
                  thank-you. Your access window expires; the
                  next release still lands publicly.

The contributor tier and the supporter tier are not the same thing. The contributor tier is permanent and earned through work; the supporter tier is temporary and acknowledges financial help. Both eventually converge at the same public release.

If you are reporting a bug

  1. Identify the chronicle. Bugs are usually chronicle-specific. "It happens in L2J_Mobius_GD_1.0_Awakening" is much more useful than "it happens in L2jMobius".
  2. Identify the file or system. The Cheat Sheet exists for exactly this, "I want to change X, where does X live?" reverses to "X is broken, what file owns X?".
  3. Provide a repro. "Login, walk to coordinates, use skill, observe stuck animation" beats "skills are broken".
  4. Note the client version. Many "bugs" are wrong-client-against-wrong-chronicle mismatches. Confirm the client matches the chronicle before filing.

If you are operating a public server

That is your project, not Mobius's. The codebase is offered for education, research, and preservation. The Mobius project explicitly does not encourage commercial server operation; commercial operation invites scrutiny that private use does not, and is governed by laws that vary by jurisdiction. See Legal.

Practical notes from the Mobius team to operators, with no warranty:

  • Treat each chronicle as its own deployment. Do not try to share a database between chronicles, the schemas differ.
  • Use the bundled db_installer SQL files for the chronicle you are running. Manually edited dumps from one chronicle do not import cleanly into another.
  • Test in a private environment before exposing the LoginServer's bridge port to anything beyond localhost.
  • Back up the database before any schema migration. Mobius migrations are forward-only.

How to get in touch

  • Forum: l2jmobius.org/forum, the canonical place for bug reports, patches, and discussion.
  • Discord: linked from the forum; useful for real-time questions and small clarifications.

Thanks to every person who has helped with development over the years. The project exists because of them. If you find this wiki useful and you spot something wrong on a page, let the team know, the wiki itself is part of the project.