> For the complete documentation index, see [llms.txt](https://tgiann.gitbook.io/tgiann/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tgiann.gitbook.io/tgiann/scripts/tgiann-npc-guide.md). # tgiann-npc-guide A story-telling guide NPC for your server. Players walk up to a configured NPC (by default a wise old man downtown for the legal side and a retired robber under the bridge for the illegal side), press the interaction key and a dialogue UI opens. Every visit the NPC tells the player one story about the server: how to find a job, how licenses work, where the workbenches are, how the robbery queue works, and so on. Stories are written by you in the config, so the NPC explains **your** server. ## Features * Any number of NPCs, each with its own model, position, scenario, lines, stories, cooldown and voice. * One new story per visit, told in config order or randomly. A per-NPC cooldown (1 hour by default) decides when the player can ask for the next one. * Everything the player has heard is saved to the database. The **What you remember** tab lists every story that was told and lets the player replay it at any time. * Dialogue UI with a typewriter effect, a skip button and a mute button. * Voice: pre-generated audio files (made with the included generator, see [Voice Generator](/tgiann/scripts/tgiann-npc-guide/voice-generator.md)), browser text to speech, or silent. Missing files can fall back to browser TTS automatically. * Cinematic camera that frames the NPC while the conversation is open. * Every text (name, title, lines, stories) can be a plain string or a language table (`{ tr = "...", en = "..." }`). The player's language picks the text; a missing language falls back to the default language. * NPC peds are only spawned when a player is close, so they cost nothing while nobody is around. ## How a conversation works 1. The player walks to the NPC. Inside `maxDistance` an interaction prompt appears; inside `pressDistance` the player can press the key to start talking. 2. The camera moves to the configured offset and the NPC greets the player with a random line from `lines.greetings` (or from `lines.waitGreetings` while the player is still on cooldown). 3. **Tell me something** asks for a new story. If the cooldown is over and untold stories remain, the NPC says a `thinking` line, then the story. The story is saved for the player and the cooldown starts. Otherwise the NPC answers with the `cooldown` line (the remaining time replaces `%s`) or the `nothingLeft` line when every story has been told. 4. **What you remember** opens the list of stories already heard (`told / total`). Clicking one makes the NPC tell it again, without touching the cooldown. 5. **Goodbye** plays a random `goodbyes` line and closes the dialogue. ## Installation 1. Make sure `tgiann-core`, `ox_lib` and `oxmysql` are installed and started before this resource. 2. Put the resource in your resources folder and add `ensure tgiann-npc-guide` to your server.cfg after `tgiann-core`. 3. The database table `tgiann_npc_guide_player` is created automatically on the first start (tgiann-core database creator). No SQL to import. 4. Edit [config.lua](/tgiann/scripts/tgiann-npc-guide/configs/config.lua.md) to place your NPCs and [configTips.lua](/tgiann/scripts/tgiann-npc-guide/configs/configtips.lua.md) to write the stories. 5. Optional: generate the voice files for your texts with the [Voice Generator](/tgiann/scripts/tgiann-npc-guide/voice-generator.md), or switch the NPC voice to `browser` / `off`. ## Commands Both commands are restricted to the `group.admin` ace. | Command | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/npcguidereset [npc] [playerId]` | Clears the story cooldown. `npc` is an NPC id from the config (leave empty for every NPC), `playerId` is the target player (leave empty for yourself). | | `/npcguidevoices` | Prints the browser TTS voices installed on your client to the F8 console. Use a part of a voice name as `tts.voiceHint`. | ## Adding a new NPC 1. Add a new entry to `config.npcGuide.npcs` in [config.lua](/tgiann/scripts/tgiann-npc-guide/configs/config.lua.md) with a unique `id`. The `id` is saved per player, so do not rename it once the script is live. 2. Add `config.npcGuideTips.` in [configTips.lua](/tgiann/scripts/tgiann-npc-guide/configs/configtips.lua.md) with the stories of this NPC. Every story needs a unique, stable `id`. 3. If the NPC should speak with audio files, add a block for its `id` in `generator/voices.json` (otherwise the `default` voices are used) and run the generator. 4. Restart the resource. ## Folder overview | Path | What it is | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `configs/config.lua` | NPCs: model, coords, lines, cooldown, camera, voice and TTS settings. | | `configs/configTips.lua` | The stories, keyed by NPC id. | | `languages/*.lua` | Notification and UI texts. | | `client/editable.lua`, `server/editable.lua` | Open (non-escrow) hooks, see [Editable Files](/tgiann/scripts/tgiann-npc-guide/editable-files.md). | | `sounds//` | Voice files, one per line / story / language. | | `generator/` | Voice generator (Python + edge-tts), see [Voice Generator](/tgiann/scripts/tgiann-npc-guide/voice-generator.md). |