# Installation

> Setup guide for ML Skills

Category: SKILLS · Source: https://miciomods.it/docs/ml-skills-installation · Last updated: 2026-07-28

## Overview

ML Skills is a live skill tree editor and player progression layer. Server staff build skill trees from inside the game, players walk them, and other resources read XP or trigger perks through 30+ public exports.

## Quick Start

1. Download from [CFX Portal](https://portal.cfx.re)
2. Extract to your `resources` folder as `ml_skills`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_skills
```

> **WARNING:** Load Order
>
> `ml_skills` must start AFTER `ml_bridge`, `ox_lib` and `oxmysql`.

## Database

Tables are created automatically on first start:

`ml_skills_players`: Per-player category XP, unspent points, unlocked skills, achievement claims

`ml_skills_trees`: Tree definitions per category, versioned, written by the in-game editor

`ml_skills_categories`: Category labels, icons and XP curves, written by the categories editor

`ml_skills_achievements`: Achievement definitions created in the admin panel

The schema includes idempotent migrations for pre-1.0 installs: dedupe of duplicate tree rows, addition of the `category` UNIQUE constraint, and the `idx_category_version` covering index used by the tree-version poller. The migrations run inside `pcall` and skip cleanly on already-healthy schemas.

## Item Registration

> **INFO:** No Items Required
>
> ML Skills does not register or require any inventory items.

## Verify

After starting, the console will print:

```lua
[ml_skills] Tables verified/created
[ml_skills] Loaded N skill categories
```

Open the UI in-game with `/skills` or the `J` key (both configurable through `Config.OpenCommand` and `Config.OpenKey`).

**Troubleshooting**

- **UI does not open**: Check the F8 console for resource errors. The keybind defaults to `J`; if another resource binds the same key, change `Config.OpenKey` and `/restart ml_skills`.
- **Skills not saving**: Confirm `oxmysql` started before `ml_skills`. Tail the server log for `[DB]` lines on boot.
- **Admin panel missing in the UI**: The current player needs the permission level set in `Config.AdminPermission.level` (default `'supervisore'`). Either grant it through `ml_bridge` or set `Config.AdminPermission.ace = 'ml_skills.admin'` and add the matching ACE rule.
- **`Bridge.* attempt to call a nil value`**, `ml_bridge` is loading after `ml_skills`. Move the `ensure ml_bridge` line above `ensure ml_skills`.
- **Tree edits revert after a restart**: Pre-1.0 schema mismatch left duplicate tree rows. Stop the resource, let the auto-migration run on next start, then verify with `SELECT category, COUNT(*) FROM ml_skills_trees GROUP BY category;` (no row should return more than 1).