Smart NPC Plugin [RPG Maker MZ]

Bring dynamic NPC conversations to your RPG Maker MZ project with NPC-GPT, the complete plugin + template combo that connects in-game events to AI-driven dialogue—no scripting required.

Easily prompt your players with fully customizable text-input windows, send their messages to your backend (REST-ready), and display rich, paginated responses using the built-in response window commands.

Join our Discord 

✅ Key Features

• 💬 Prompt players anywhere: fire the userInput command from any event to gather text, limit word counts, and route the result into switches or variables.
• 🎨 Totally skinnable UI: pick background style (window/dim/transparent), rows, width, position, face portraits, button labels, placeholder text, and more.
• 🧠 Ready for AI pipelines: ships with commands that package input/output into JSON, making it easy to hit your own server (or NPC-GPT cloud) and bring responses back into events.
• 🪄 Smart response windows: the new displayResponse command shows multi-page replies, supports actor faces, name boxes, and shares the same styling controls as the input window.
• ⚙️ Event-friendly flow: interpreter wait modes are handled for you—events resume only after players finish typing, confirm responses, or close the window.
• 🧱 Built for extension: exposes shared helper objects so you can hook in logging, analytics, cooldowns, or other custom systems with minimal effort.

📦 What’s Inside

• 🧪 A complete browser-playable template project (also downloadable) showcasing live input + response chains.
• 📁 NPC-GPT-Plugin.js ready to drop in your own projects.
• 📑 Example events demonstrating prompt → fetch → response handling, variable storage, and branching control flow.

🛠 How to Use

1. Download and extract the template project (try it online, then grab the files).
2. Copy js/plugins/NPC-GPT-Plugin.js into your project’s js/plugins/ folder.
3. Add any sample assets you want (faces, windowskins, etc.) to the standard img/ directories.
4. In the RPG Maker MZ editor:
   • Open Plugin Manager → add NPC-GPT-Plugin.
   • Review the default parameters (API key variable, response storage, etc.).
   • Import the example common events or recreate your own using the plugin commands below.
5. Create a free account at gamertoolstudio.com and get an API key
6. Add the API Key to its respective Plugin Parameter
7. Playtest: trigger userInput, hit your server, show the displayResponse, and continue your event logic once players confirm.

🧩 Plugin Parameters

Parameter	Description
API Key	Your personal API KEY from gamertoolstudio.com
API Key	Game variable storing your API key (or fallback static key)
GPT Response Variable	Stores serialized chat history (JSON string)

⚙️ Plugin Commands

userInput

prompt the player for text using a fully configurable input window. Supports background style, size, position, rows, placeholder, confirm/cancel labels, word caps, actor face/name boxes, and variable IDs for storing input.

Argument	Description
windowPosition	Position of the window (top, middle, bottom).
windowWidth	Custom width in pixels; 0 = full width.
windowRows	Visible rows for the input field.
background	Background skin (window, dim, transparent).
placeholderText	Hint text shown when the input is empty.
inputVariable	Variable ID where the player’s input is stored.
maxInputWords	Maximum number of words the player can enter (0 = unlimited).
actorFaceImage	Face graphic (img/faces) to show beside the window.
actorFaceImageIndex	Face index (0–7) within the chosen face graphic.
actorName	Optional speaker name shown above the window.
closeEventButtons	yes/no to show confirm + cancel buttons.
confirmButtonText	Text label for the confirm button.
cancelButtonText	Text label for the cancel button.

sendRequest

Shows how to package the user’s input, chat history, and character context into JSON and send it to your API endpoint.

Argument	Description
historyVariableId	Variable ID containing chat history (JSON string).
contextVariableId	Variable ID storing the character context payload.
inputVariable	Variable ID holding the latest user input text.
responseStatusVariable	Variable ID updated to track success/failure.
maxOutputWords	Numeric hint you can forward to your backend (0 = ignore).

characterContext

Stores character traits/background info in variables to seed requests (e.g. personality, knowledge, location).

Argument	Description
name	Character name to store in context.
age	Character age.
traits	Personality traits string.
dialogueStyle	Suggested speaking style for the AI.
backgroundStory	Backstory text.
eventsKnowledge	JSON string describing what the character knows.
environment	JSON string describing the current environment.
interests	Interests string (comma-separated or JSON).
friendliness	enemy, low, regular, high, best friend.
contextVariableId	Variable ID where the compiled context will be stored.

displayResponse

Render stored text in a matching response window. Shares styling controls with the input window, supports faces/name boxes, handles pagination (OK to advance, Cancel to exit), and resumes the calling event automatically.

Argument	Description
eventId	Event to resume after the window closes (default: current event).
eventPageId	Page to resume when the window closes (default: 0).
actorImage	Face image (img/faces) displayed in the response window.
actorImageIndex	Index (0–7) within the face image.
actorName	Name label shown above the response window.
wrapTextLength	Hard wrap length (character count); 0 = wrap by width.
windowPosition	Position of the response window (top, middle, bottom).
windowRows	Visible rows per page before pagination.
windowWidth	Custom width; 0 = full width.
background	Response window skin (window, dim, transparent).
responseStatusVariable	Variable reset to 0 after the window closes.

📥 Installation Recap

1. Add NPC-GPT-Plugin.js to js/plugins/.
2. Configure plugin parameters (API/key variables, defaults, etc.).
3. Use the template events—or build your own—to gather input, send it to your backend, store the response, and call displayResponse.
4. Customize backgrounds, sizes, labels, and sounds in Plugin Parameters.

Compatibility

RPG Maker MZ

Terms of Use

• Usable in free and commercial games.
• Credit Gamer Tool Studio in your project.
• You may edit the plugin for your own use (do not rename the file).
• Redistribution of the plugin itself is not allowed.
• Do not extract code for your own released plugins.

Ready to give your NPCs real conversations? Drop in the plugin, hook up your AI backend, and let players chat their way through your world.