Configure

Requirements

FS-Lib

Optional:

ox_lib for text UI interaction prompts
ox_target for target-based interaction points
lation_ui for lation text prompts
qbx_core, qb-core, or es_extended for job-based page and point permissions

Installation

Copy the FS-Handbook resource folder into your server's resources directory.

Start FS-Lib before FS-Handbook in server.cfg:

ensure FS-Lib
ensure FS-Handbook

Open configuration/config.lua and configure permissions, defaults, history, feedback, and integrations. Handbook pages and interaction points are edited in-game and saved to data/handbook.json.

Restart your server, or restart the FS-Handbook resource from the server console.

Permissions

Config.AdminAce controls access to saving handbook edits and opening the admin editor.

Prop

Type

Example server.cfg:

add_ace group.admin handbook.admin allow

Pages, categories, and interaction points can also use perm in data/handbook.json. Supported permission values are:

null or omitted: visible to everyone.
false: hidden from non-admin player views.
"ace.permission": require an ACE permission.
{ "type": "job", "jobs": ["police", "ems"] }: require a supported framework job.

Interaction settings

Prop

Type

Interaction points can open the full handbook or a specific page. Points support marker mode, NPC mode, GTA help text, ox_lib, ox_target, and lation_ui prompts.

Keybinds and commands page

Config.KeybindsAndCommands controls the built-in page that lists registered commands and detected key mappings.

Prop

Type

Save history

Config.History stores a compact snapshot before each successful handbook save.

Prop

Type

Player feedback

Config.Feedback controls page reports submitted by players and reviewed from the admin editor.

Prop

Type

Handbook data

The live handbook is stored in data/handbook.json. If the file is missing or empty, FS-Handbook creates a starter handbook automatically.

Top-level shape:

{
  "categories": [],
  "pages": [],
  "points": []
}

Page fields:

Prop

Type

Interaction point fields:

Prop

Type

NPC scenarios and animations

The NPC editor provides Search and Manual modes for both behaviors:

Search uses the bundled GTA scenario and animation reference catalogs.
Manual accepts a scenario name or animation dictionary/name that is not in the catalog.
A scenario and animation are mutually exclusive. When npc.scenario is set, FS-Handbook clears and ignores npc.animation.
Scenario compatibility depends on the NPC model, placement, and current GTA/FiveM game build.
Selected or applied animation dictionaries are load-tested on the client. GTA/FiveM cannot reliably prevalidate every animation clip name.

Game build compatibility

If a referenced scenario or animation does not play, the current GTA/FiveM game build may not include or support it. Animation validation stops after 3 seconds, and NPC animation loading stops after 5 seconds. A failed animation leaves the NPC idle instead of waiting forever. An invalid or incompatible scenario also does not block the client.

NPC behavior fields:

Prop

Type

Scenario example:

{
  "id": "sheriff-dog",
  "name": "Sheriff Dog",
  "mode": "npc",
  "coords": { "x": 440.1, "y": -981.2, "z": 30.7, "w": 90.0 },
  "npc": {
    "model": "a_c_shepherd",
    "scenario": "WORLD_DOG_SITTING_SHEPHERD"
  }
}

Animation example:

{
  "id": "city-hall-clerk",
  "name": "City Hall Clerk",
  "mode": "npc",
  "coords": { "x": -545.0, "y": -204.0, "z": 38.0, "w": 210.0 },
  "npc": {
    "model": "s_m_m_highsec_01",
    "scenario": "",
    "animation": {
      "dict": "amb@world_human_clipboard@male@idle_a",
      "name": "idle_c",
      "flags": 1
    }
  }
}

Commands

/handbook opens the player handbook.
/handbookadmin opens the admin editor when the player has Config.AdminAce.Ace.

Both commands are registered with FiveM key mapping. Players can bind them in FiveM keybind settings.

Exports

See Exports for server and client exports.