improve skill and doc

Author: RSamaium

.codex

@@ -11,6 +11,7 @@ docs/others/*
 !docs/api/player/*.md
 !docs/api/map/
 !docs/api/map/*.md
+!docs/api/*.config.json
 !docs/api/client/
 !docs/api/client/*.md
 !docs/others/readme.md

.gitignore

@@ -0,0 +1,39 @@
+{
+  "title": "Map API",
+  "description": "Reference for RpgMap, map controls, and event hooks used by created events.",
+  "basePath": "api/map",
+  "index": {
+    "title": "Map API",
+    "description": "Reference for RpgMap, world map helpers, controls, and event hooks used by created events.",
+    "intro": "This reference is generated from the JSDoc comments in `packages/server/src/rooms/map.ts` and `packages/common/src/rooms/WorldMaps.ts`."
+  },
+  "sections": [
+    {
+      "title": "RpgMap",
+      "description": "Reference for the `RpgMap` class.",
+      "output": "rpg-map.md",
+      "ownerNames": ["RpgMap"],
+      "sourceFiles": ["packages/server/src/rooms/map.ts"]
+    },
+    {
+      "title": "World Maps",
+      "description": "Reference for world map helpers.",
+      "output": "world-maps.md",
+      "sourceFiles": ["packages/common/src/rooms/WorldMaps.ts"]
+    },
+    {
+      "title": "Map Types",
+      "description": "Supporting interfaces related to map controls.",
+      "output": "map-types.md",
+      "ownerNames": ["Controls"],
+      "sourceFiles": ["packages/server/src/rooms/map.ts"]
+    },
+    {
+      "title": "Event hooks",
+      "description": "Hooks for events created as plain objects, as shown in the create-event guide.",
+      "output": "hooks.md",
+      "ownerNames": ["EventHooks"],
+      "sourceFiles": ["packages/server/src/rooms/map.ts"]
+    }
+  ]
+}

docs/api/map.config.json

@@ -0,0 +1,135 @@
+---
+title: "Event hooks"
+description: "Hooks for events created as plain objects, as shown in the create-event guide."
+---
+
+# Event hooks
+
+These are the hooks for events created as plain objects, as shown in [Create an event](/guide/create-event).
+
+## Members
+
+- [onAction](#onaction)
+- [onChanges](#onchanges)
+- [onDetectInShape](#ondetectinshape)
+- [onDetectOutShape](#ondetectoutshape)
+- [onInit](#oninit)
+- [onInShape](#oninshape)
+- [onOutShape](#onoutshape)
+- [onPlayerTouch](#onplayertouch)
+
+## onAction
+
+Called when a player performs an action on this event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onAction: (player: RpgPlayer) => void
+```
+
+## onChanges
+
+Called during the change-detection cycle for the current player.
+
+Use this hook to recompute the event state from player data, especially player variables. This is useful for reactive visuals such as an opened chest, a hidden door, or a conditional NPC graphic.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onChanges: (player: RpgPlayer) => void
+```
+
+## onDetectInShape
+
+Called when a player is detected entering a detection shape attached to the event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onDetectInShape: (player: RpgPlayer, shape: RpgShape) => void
+```
+
+## onDetectOutShape
+
+Called when a player is detected exiting a detection shape attached to the event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onDetectOutShape: (player: RpgPlayer, shape: RpgShape) => void
+```
+
+## onInit
+
+Called when the event is first initialized.
+
+Use this hook for default setup that does not depend on a player interaction, such as setting the initial graphic, speed, or movement route.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onInit: () => void
+```
+
+## onInShape
+
+Called when a player enters a shape attached to the event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onInShape: (zone: RpgShape, player: RpgPlayer) => void
+```
+
+## onOutShape
+
+Called when a player exits a shape attached to the event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onOutShape: (zone: RpgShape, player: RpgPlayer) => void
+```
+
+## onPlayerTouch
+
+Called when a player touches this event.
+
+- Source: `packages/server/src/rooms/map.ts`
+- Kind: `property`
+- Defined in: `EventHooks`
+
+### Signature
+
+```ts
+onPlayerTouch: (player: RpgPlayer) => void
+```

docs/api/map/hooks.md

@@ -1,6 +1,6 @@
 ---
 title: "Map API"
-description: "Reference for RpgMap and world map helpers."
+description: "Reference for RpgMap, world map helpers, controls, and event hooks used by created events."
 ---
 
 # Map API
@@ -12,3 +12,4 @@ This reference is generated from the JSDoc comments in `packages/server/src/room
 - [RpgMap](/api/map/rpg-map)
 - [World Maps](/api/map/world-maps)
 - [Map Types](/api/map/map-types)
+- [Event hooks](/api/map/hooks)

docs/api/map/index.md

@@ -1,11 +1,11 @@
 ---
 title: "Map Types"
-description: "Supporting interfaces related to map controls and event hooks."
+description: "Supporting interfaces related to map controls."
 ---
 
 # Map Types
 
-Supporting interfaces related to map controls and event hooks.
+Supporting interfaces related to map controls.
 
 ## Members
 
@@ -14,14 +14,6 @@ Supporting interfaces related to map controls and event hooks.
 - [maxInputsPerTick](#maxinputspertick)
 - [maxTimeDelta](#maxtimedelta)
 - [minTimeBetweenInputs](#mintimebetweeninputs)
-- [onAction](#onaction)
-- [onChanges](#onchanges)
-- [onDetectInShape](#ondetectinshape)
-- [onDetectOutShape](#ondetectoutshape)
-- [onInit](#oninit)
-- [onInShape](#oninshape)
-- [onOutShape](#onoutshape)
-- [onPlayerTouch](#onplayertouch)
 
 ## enableAntiCheat
 
@@ -92,115 +84,3 @@ Minimum time between inputs in milliseconds
 ```ts
 minTimeBetweenInputs: number
 ```
-
-## onAction
-
-Called when a player performs an action on this event
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onAction: (player: RpgPlayer) => void
-```
-
-## onChanges
-
-Called when the event properties change
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onChanges: (player: RpgPlayer) => void
-```
-
-## onDetectInShape
-
-Called when a player is detected entering a shape
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onDetectInShape: (player: RpgPlayer, shape: RpgShape) => void
-```
-
-## onDetectOutShape
-
-Called when a player is detected exiting a shape
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onDetectOutShape: (player: RpgPlayer, shape: RpgShape) => void
-```
-
-## onInit
-
-Called when the event is first initialized
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onInit: () => void
-```
-
-## onInShape
-
-Called when a player enters a shape
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onInShape: (zone: RpgShape, player: RpgPlayer) => void
-```
-
-## onOutShape
-
-Called when a player exits a shape
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onOutShape: (zone: RpgShape, player: RpgPlayer) => void
-```
-
-## onPlayerTouch
-
-Called when a player touches this event
-
-- Source: `packages/server/src/rooms/map.ts`
-- Kind: `property`
-- Defined in: `EventHooks`
-
-### Signature
-
-```ts
-onPlayerTouch: (player: RpgPlayer) => void
-```

docs/api/map/map-types.md

@@ -1,11 +1,21 @@
 ---
 title: "Variable Commands"
-description: "Store and retrieve arbitrary player variables."
+description: "Store and retrieve player variables that persist across saves and map transfers."
 ---
 
 # Variable Commands
 
-Store and retrieve arbitrary player variables.
+Store and retrieve player variables.
+
+Player variables are not just generic temporary values.
+
+They are primarily used to:
+
+- persist player-specific state for saves
+- keep player state when moving from one map to another
+- transfer that state through the player snapshot, even if the next map is hosted on another server
+
+Use them for quest flags, chest states, dialogue progression, switches, and any per-player value that must survive reconnects and map changes.
 
 ## Members
 
@@ -117,7 +127,9 @@ true if a variable existed and has been removed, false otherwise
 
 ## setVariable
 
-Assign a variable to the player
+Assign a variable to the player.
+
+Use this for player state that must be persisted and restored later, such as quest progression or whether a personal chest has already been opened.
 
 - Source: `packages/server/src/Player/VariableManager.ts`
 - Kind: `method`
@@ -137,7 +149,9 @@ setVariable(key: string, val: any): void
 
 ## variables
 
-Map storing all player variables
+Map storing all player variables.
+
+These values belong to the player, are persisted, and travel with the player snapshot during map changes.
 
 - Source: `packages/server/src/Player/VariableManager.ts`
 - Kind: `property`

docs/api/player/variable-commands.md

@@ -128,6 +128,7 @@
           {
             "group": "Hooks",
             "pages": [
+              "api/map/hooks",
               "hooks/client-engine-hooks",
               "hooks/client-physics-hooks",
               "hooks/client-scene-hooks",