# IMAGE-NPC Machine **A unified NPC modeling and management station for OpenSim** Part of the IMAGE engine framework Designed by Dirty Helga & Spax Orion License: CC BY-NC --- ## What It Is The IMAGE-NPC Machine is a four-prim modeling station that lets you create, preview, customize, and manage NPCs in your OpenSim region — all from a single linkset. - Snapshot any avatar's appearance and save it as a notecard - Rez NPCs from saved appearance cards for preview - Cycle animations on the rezzed NPC for posing - Browse, swap, take, or delete appearance cards - Scan the region for NPCs and remove them individually or all at once The machine accepts only NPCs as occupants. Avatars who try to sit on it are silently rejected — this is a tool, not a clickbox. --- ## Requirements - OpenSim 0.9.x (tested on 0.9.2.1 Yeti with Mono, XEngine, BulletSim) - OSSL functions enabled, specifically: - `osAgentSaveAppearance` - `osNpcCreate` - `osNpcSit` - `osNpcStand` - `osNpcRemove` - `osNpcLoadAppearance` - `osIsNpc` - `osGetAvatarList` - `osAvatarPlayAnimation` - `osAvatarStopAnimation` - Owner permissions on the region or parcel where you place the machine --- ## Two-Step Deployment The IMAGE-NPC Machine ships as two scripts. The first builds the linkset; the second powers it. ### Step 1: Build the Linkset 1. Rez **four default cube prims** anywhere in your region 2. Select all four, then link them — the **last selected becomes the root** 3. Open the root prim's contents and drop in `BUILD IMAGE-NPC Machine.lsl` 4. **Touch the linkset once** 5. The assembler will reshape and color all four prims into the IMAGE-NPC Machine 6. After 3 seconds, the assembler script removes itself You should now see the finished machine: a tapered cylinder base with three smaller cylindrical control rings beside it — yellow, red, and cyan markers identifying their functions. ### Step 2: Install the Engine 1. Open the root prim's contents 2. Drop in the IMAGE script (`Image-NPC-Machine.lsl`) 3. Wait for the script to compile and report ready The machine is now operational. --- ## Anatomy of the Machine | Link | Name | Marker | Function | |------|------|--------|----------| | 1 | IMAGE-NPC-Machine | (root, the stand) | Modeling stand — NPCs sit here for animation cycling | Touch the base of the root prim to cycle the standing poses you add to it. | 2 | NPC sorter | yellow | Touch for the appearance preview menu | | 3 | NPC Gen | red | Touch to snapshot your appearance into a notecard | | 4 | NPC Mgr | cyan | Touch for the region NPC management menu | --- ## How To Use It ### Saving Your Appearance to a Card This is how you populate the machine's library of looks. Stand near the machine and **touch the red Gen prim**. The machine will: - Save your current appearance as a notecard named `NPC-card_1` (or `NPC-card_2`, `NPC-card_3`, etc., auto-numbered) - Reset itself to load the new card into its library - Confirm the save in local chat If an NPC is currently seated on the machine, the Gen button is disabled. Remove the NPC first. After saving, you can rename the `NPC-card_` notecard in the root prim's inventory to whatever you want — `Wanda Worker`, `Pirate Captain`, `Glowing Pigeon Handler`, whatever fits. The machine reads all notecards in the root prim's inventory as available appearances. ### Previewing an NPC Touch the **yellow Sorter prim**. A dialog menu opens showing the current appearance card and a set of buttons: | Button | Function | |--------|----------| | **REZ** | Spawns an NPC using the current appearance card and seats it on the modeling stand | | **<< PREV** | Shows the previous appearance card (and swaps the seated NPC's look if one is rezzed) | | **NEXT >>** | Shows the next appearance card | | **KILL** | Removes the seated NPC but keeps the card | | **TAKE** | Gives you the current card AND removes the NPC AND deletes the card from the machine (one clean action with confirmation) | | **DELETE** | Permanently removes the current appearance card from the machine's inventory | | **DONE** | Closes the menu | When an NPC is seated, you can also browse animations directly by touching the **curved side of the root prim** — left half goes to the previous animation, right half to the next. The animations available are whatever animation files you've placed in the root prim's inventory. ### The TAKE Workflow TAKE is the workflow for finalizing a look. Once you've previewed an NPC and you're happy with it: 1. Press TAKE 2. Confirm with "Yes" in the confirmation dialog 3. The appearance card is delivered to your inventory 4. The NPC is removed 5. The card is deleted from the machine You can then rename the card in your inventory and use it elsewhere — drop it into another NPC rezzer, archive it, share it. ### Managing Region NPCs Touch the **cyan Mgr prim** to scan the region for all NPCs. A menu opens listing each NPC by number with its name, plus: - **Numbered buttons** — kill that specific NPC - **KILL ALL** — removes every NPC currently in the region (instant, no confirmation) - **MORE** — paginates if there are more NPCs than fit on one menu - **DONE** — closes the menu If you accidentally KILL ALL while you have an NPC seated on the modeling stand, the machine handles cleanup correctly and resets its tracking. --- ## Adding and Managing Animations The machine cycles through animations placed in the root prim's inventory. To add new animations: 1. Open the root prim's contents 2. Drag animation files (BVH-imported or any inworld animation asset) into the inventory 3. The script will automatically rebuild its animation list There's no menu for animations — they're paged purely by touching the curved side of the root prim while an NPC is seated. The machine plays them through OSSL `osAvatarPlayAnimation`, which works on NPCs without needing permission grants. --- ## Owner-Only Every interactive function on the machine is owner-only. Anyone else who touches any prim gets nothing — no error message, no menu, no acknowledgment. The machine is a private tool. If you want to share it, share the build, not access to your machine. --- ## Troubleshooting **The machine doesn't build when I touch the assembler** Make sure you have exactly four prims in the linkset. The assembler will refuse to run on any other count and will tell you so in local chat. **Touching the Gen prim does nothing** You probably have an NPC seated on the modeling stand. Remove it first via the Sorter menu's KILL button, then try Gen again. **The Sorter menu says "No cards in sorter, add some."** The machine has no appearance notecards in its inventory. Use the Gen prim to snapshot at least one appearance, or drop in appearance cards manually. **An avatar sat on the machine and got immediately stood up** That's correct behavior. The machine rejects all avatars and accepts only NPCs. **Touching the root prim does nothing** Also correct — the root prim's animation cycling only responds when an NPC is seated. Without one, it ignores you. **Animations aren't playing on the seated NPC** Verify there are animation assets in the root prim's inventory. The machine reads them on `state_entry` and rebuilds the list on inventory changes. If you just added animations, give it a moment to rebuild. **The dialog menu times out** Menus auto-close after 120 seconds of no input. Just touch the prim again to reopen. --- ## Technical Notes ### Why OSSL Throughout Earlier NPC tools relied on `llRequestPermissions` and the human animation permission system, which created race conditions and required handshakes that didn't fit how NPCs work. The IMAGE-NPC Machine uses `osAvatarPlayAnimation` and `osAvatarStopAnimation` exclusively for animation control. Since NPCs don't need to grant permissions, this is faster, cleaner, and avoids the brittle timing issues that plagued older designs. ### Why the NPC Sit Race Was Fixed The Paramour NPC Manager and similar older scripts used a `llSleep(0.25)` after `osNpcCreate` and hoped the NPC would be ready to sit. On Yeti this was unreliable. The IMAGE-NPC Machine uses `changed(CHANGED_LINK)` to detect when the NPC has actually landed on the sit target — only then does it stop the default sit animation and apply the current pose. No blind sleeps, no praying. ### Why Everything Is in the Root The original cobbled version had four scripts across four prims, with a `link_message(56)` relay between them and inventory shuttled across links via `llGiveInventory`. This worked but was fragile. The unified design holds all logic, all animations, and all appearance notecards in the root prim. The child prims are pure touch surfaces — they exist only to give the user a target to click. Touch routing happens via `llDetectedLinkNumber()` in the root. ### The Self-Deleting Assembler The assembler script's only job is to take a fresh four-cube linkset and shape it into the IMAGE-NPC Machine. Once the build is complete, it has no further purpose, so it removes itself with `llRemoveInventory(llGetScriptName())`. This keeps the finished machine clean and prevents accidental rebuilds. --- ## Credits - **Original NPC Manager** — Aine Caoimhe (Mata Hari) / LACM, April 2015 — provided the base region scanner and appearance sorter logic that was rebuilt for this version - **Engine Architecture** — Dirty Helga & Spax Orion - **Testing Grid** — xoaox.de:7000/Dismayland on the IMAGE framework --- ## License CC BY-NC — Creative Commons Attribution-NonCommercial. Use it, modify it, share it, build with it. Don't sell it. Credit Dirty Helga and Spax Orion when redistributing.