New Script

WorldAwareNPC/README.md

@@ -0,0 +1,156 @@
+# World-Aware NPC Generator
+
+A world-aware random NPC generator for Roll20 Mod scripts.
+
+Created by **Kingkiller546** — Roll20 ID **2978722**.
+
+## What it does
+
+The generator creates a compact GM-only NPC card containing:
+
+- Name
+- Sex
+- Race
+- Origin
+- Age
+- Affluence
+- Influence
+- Faction, when relevant
+
+Names are selected from ancestry- and origin-aware pools rather than from one universal fantasy-name list. Dwarves, elves, halflings, dragonborn, orcs and other supported ancestries use distinct linguistic naming conventions. Humans use broad regional naming styles. Mixed-ancestry characters use their origin as cultural upbringing.
+
+Changelings receive an assumed ancestry appropriate to their origin. Their card shows both the truth and disguise, such as “Changeling — posing as Human”, while their public name comes from the assumed identity.
+
+Influence is rolled before faction. When the result is **No Influence**, faction is not rolled or displayed.
+
+## Requirements
+
+- A Roll20 campaign with access to Mod scripts.
+- The script installed and enabled in the campaign's Mod Scripts page.
+
+The generator uses Roll20 Rollable Tables and the persistent state object. It does not make external web requests.
+
+## Installation
+
+1. Open the Roll20 campaign.
+2. Open **Settings → Mod Scripts**.
+3. Create a new script.
+4. Paste the complete contents of NPCgen.js.
+5. Save the script.
+6. In Roll20 chat, run:
+
+       !npc-config
+
+7. Select **Install Missing Tables**.
+8. Open the NPC selector with:
+
+       !npc-menu
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| !npc | Generate an NPC and whisper the card to the GM. |
+| !npc-menu | Open a GM-only selector for random or chosen origins and races. |
+| !npc-config | Open the GM-only Setup Manager. |
+| !npc-check | Check that required tables exist and contain items. |
+
+## Setup Manager
+
+- **Install Missing Tables** creates only tables that do not already exist.
+- **Repair Defaults** adds default items missing from installed tables.
+- **Factions: On/Off** enables or disables faction generation.
+- **NPC Selector** opens the origin/race selector.
+- **Generate NPC** produces a test NPC.
+
+Installing missing tables does not overwrite an existing table. Repairing defaults does not change existing items or weights, but it will restore any default item whose name is absent. Do not use **Repair Defaults** if you intentionally removed default items and do not want them restored.
+
+## Rollable Tables
+
+The script installs:
+
+- NPC-Race
+- NPC-Age
+- NPC-Sex
+- NPC-Origin
+- NPC-Affluence
+- NPC-Influence
+- NPC-Faction
+
+All generation respects Roll20 table-item weights. Change a result's likelihood by changing its weight in the Rollable Table Manager.
+
+## Customisation
+
+You may add, remove, rename or reweight items. The generator reads the live tables whenever it generates an NPC.
+
+The supplied generic origins are:
+
+- Central Kingdoms
+- Northern Kingdoms
+- Western Freeholds
+- Southern Continent
+- Island Nations
+- Floating Isles
+- Elven Realms
+- Orc Territories
+
+Renaming an origin may cause it to fall back to the general Medieval Human pool unless the corresponding key is also added to ORIGIN_PROFILES in the script.
+
+Custom races without a configured language pool use the Human pool associated with their origin.
+
+## Using it from a macro
+
+Create a Roll20 macro containing:
+
+    !npc-menu
+
+A menu button can open the selector directly:
+
+    [NPC Generator](!npc-menu)
+
+You can also call selections directly:
+
+    !npc --origin "Southern Continent"
+    !npc --race "Human"
+    !npc --origin "Southern Continent" --race "Human"
+
+The origin and race must match items in the live NPC-Origin and NPC-Race tables. Use `Random` in either selector prompt to leave that field random.
+
+## Generated card
+
+The output is whispered to the GM and is not added to the archived chat log. A selected origin or race is preserved by **Repeat Selection**. **New Selection** returns to the selector, and **Setup** opens the Setup Manager.
+
+Faction is hidden when Influence is **No Influence**, or when faction generation has been disabled through the Setup Manager.
+
+## Troubleshooting
+
+Run !npc-check and confirm every required table has at least one item. Table names must match exactly.
+
+If a custom origin uses unexpected Human names, add its text to the correct ORIGIN_PROFILES keys array.
+
+If faction does not appear, check the Influence result and confirm factions are enabled in !npc-config.
+
+## Updating
+
+Replace the previous script contents with the new version and save. Existing Rollable Tables and weights remain in the campaign. Run !npc-check after updating.
+
+Avoid deleting and reinstalling tables unless you intend to lose custom table changes.
+
+## Version history
+
+### 1.1.0
+
+- Added a GM-only origin and race selector.
+- Supports fully random, chosen origin, chosen race, or both.
+- Selector choices are read from the live Rollable Tables.
+- Added repeat-selection and new-selection card buttons.
+- Updated public branding to NPCgen.
+
+### 1.0.0
+
+- Initial public release.
+- Automated table installation and validation.
+- Race- and origin-aware naming.
+- Changeling assumed identities.
+- Optional faction generation.
+- Compact Roll20-safe output card.

WorldAwareNPC/script.json

@@ -0,0 +1,9 @@
+{
+  "name": "WorldAwareNPC",
+  "script": "WorldAwareNPC.js",
+  "version": "1.1.0",
+  "previousversions": ["1.0.0"],
+  "description": "A GM-only, world-aware NPC generator for Roll20. Creates and manages weighted rollable tables for race, age, sex, origin, affluence, influence, and faction; generates ancestry- and origin-aware names; supports Changeling assumed identities; and provides an interactive setup manager.",
+  "authors": "Kingkiller546",
+  "roll20userid": "2978722"
+}