> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/getting-started/installation.md).

# installation

## Server

Use Java 21, Minecraft 1.21.1, NeoForge 21.1.200 or newer in the supported 21.1 line, and a compatible Pixelmon 9.4.x installation. The server mod's declared Pixelmon range is `[9.4.0,9.5)`; it is not a guarantee against every API change in that range.

{% stepper %}
{% step %}

## Stop the server and create a backup

Back up the world, player data, and existing `config/stellarskills` directory.
{% endstep %}

{% step %}

## Install the server mod

Put the StellarSkills **server** jar in the server's `mods` directory. Remove duplicate versions of that same mod.
{% endstep %}

{% step %}

## Start the server

Start the server once. StellarSkills creates missing files under `config/stellarskills` and initializes its database.
{% endstep %}

{% step %}

## Review configuration files

Review `classes.yml`, `leveling.yml`, and `objectives.yml` before inviting players.
{% endstep %}

{% step %}

## Validate the installation

Run `/skills admin validate`, then `/skills admin status`. Investigate errors in `logs/latest.log`.
{% endstep %}
{% endstepper %}

The server does not need the optional rendering client to calculate buffs. Players without it use fallback inventory menus for skills/classes and text commands for quests/effect choices. Do not put a client-only engine on a dedicated server as a substitute for StellarSkills.

## Custom client

Install one compatible StellarEngine build on participating clients. 

The engine provides custom classes, skill trees, profile, Journey, rankings, quest journal, effect choices, and authorized authoring screens. The server editor requires the compatible client. Player accessibility preferences do not change server-authored theme selection or gameplay rules.

## Upgrade safely

* Replace incompatible server/client builds together, with the game/server stopped.
* Existing files are normally retained rather than replaced with new defaults. Missing general settings and English locale keys are merged; other existing files are not automatically rebuilt.
* New packaged examples may therefore be absent from an older live server. Copy only the desired entries, then validate.
* Never remove the database to make a new option appear. It contains ranks, balances, Hero decisions, class selections, quest progress, and reward history.
* Changing `client.protocol` does not make an old client compatible: protocol 20 is compiled into the networking code.

## What does not happen automatically

The class selection screen is not meant to open on every join. `/skills` routes unqualified players to classes and qualified players to an accessible skills tree. Selecting a class does not give access to every tree when `restrict-tree-access` is enabled.

The mod does not generate README files in the server configuration directory. Generated YAML omits standalone `#` comment lines. This documentation package is a separate deliverable, not a startup-generated file.