AI Dialogue RPG Maker MZ

RPGツクール プラグイン
,
1

RPG Maker MZ AI Dialogue

I was programming in Python as usual and using GROQ’s API, and I thought, why not create something for RPG Maker MZ too?

Since I just finished developing my FOW Minimap, I sat down and wrote some quick code.

I’m giving it away here for free, I’m not developing it further. Take it and do whatever you want – MIT License. I made it as a hobby project, it’s not a plugin I’ll maintain. Here’s what this version offers:**

1778795067760.png
1778795067760.png628×292 33.3 KB

1778795090520.png
1778795090520.png479×407 43 KB

GroqNPC.js – AI-Powered Dynamic NPC Engine for RPG Maker MZ​

Version: 2.2.0
License: MIT – do whatever you want with it
Requirements: RPG Maker MZ, Groq API key (free tier available)

What’s Inside​

This plugin connects your RPG Maker MZ game to Groq’s fast LLM API (Llama 3.1) to deliver four integrated systems:

Layer - Feature - What It Does**
1 - AI Dialogue - Streaming conversations with memory, 10s timeout
2 - Quest Machine - Define quests; all NPCs share state automatically
3 - NPC Knowledge - NPCs know quest status, companions, world state
4 - Enemy Behavior - AI decides tactics, sets MZ switches before battle

Quick Start – Dragon Hunt Example​

1. Define the quest (in an autorun event)​

Code:

Plugin Command: Define Quest
  Quest ID: dragon_hunt
  Title: The Dragon of Ashvale
  Objectives: Talk to Mark|Find the lair|Defeat the dragon
  NPC Members: Mark,Sera,Old Tom
  Quest Switch: 10
  Quest Variable: 11

​

2. Train Mark – the quest giver (in his event)​

Code:

Plugin Command: Train NPC Persona
  Name: Mark
  Personality: You are Mark, a grizzled dragon hunter. You lost your left eye to the Ashvale Dragon 20 years ago. You speak in a gruff, tired voice and constantly warn about danger.
  Role: questgiver
  Quest ID: dragon_hunt
  Guardrails: Never tell the player the dragon is easy to beat
  Fallback Message: I ain't lyin' to you about that beast.
Plugin Command: Start AI Dialogue.

3. Train a companion (Sera’s event)​

Code:

Plugin Command: Train NPC Persona
  Name: Sera
  Personality: You are Sera, a young eager mage who wants to prove herself. You admire Mark but think he's too cautious. You speak quickly and enthusiastically.
  Role: companion
  Quest ID: dragon_hunt
  Max Tokens: 150

Plugin Command: Start AI Dialogue

4. Enemy behavior – before dragon battle​

Code:

Plugin Command: Evaluate Enemy Behavior
  Enemy Name: Ashvale Dragon
  Enemy Description: Ancient red dragon, wounded but enraged. Scales are cracked on the left side (Mark's old wound). Breathes fire every 3 turns.
  Quest ID: dragon_hunt
  Behavior Switch Base: 20
  Player HP % Variable: 1

Then check switches in your battle event:

  • Switch 20 ON → Aggressive (full attack)
  • Switch 21 ON → Defensive (guard/buff)
  • Switch 22 ON → Flee (escape attempt)
  • Switch 23 ON → Reinforce (call allies)
  • Switch 24 ON → Enraged (berserk mode)

5. Advance the quest anywhere​

Code:

Plugin Command: Advance Quest Objective
  Quest ID: dragon_hunt

All NPCs linked to dragon_hunt will automatically know the new objective.

Text Formatting (AI → MZ Color Codes)​

The AI wraps key words with semantic tags. The plugin converts them to MZ colors:

Tag - Purpose - MZ Color

Code:

[important]text[/important]
  • Dangers, warnings, critical info - Red (2)

Code:

[highlight]text[/highlight]
  • Names, places, items, proper nouns - Yellow (14)

Code:

[secret]text[/secret]
  • Secrets, rare knowledge, confidential - Green (3)

Code:

[weak]text[/weak]
  • Rumors, uncertain info, vague hints - Gray (8)

Example AI response:

Code:

DIALOGUE: The [highlight]Dragon of Ashvale[/highlight] sleeps near the
[highlight]eastern caves[/highlight]. It is [important]extremely dangerous[/important]
– its fire can melt steel in seconds.

PROMPT: Ask about the weak spot?

What the player sees: Colored text automatically (yellow for locations, red for warnings, etc.)

⚙️ Plugin Parameters (Configure in Plugin Manager)​

Parameter - Default - Description

Code:

Groq API Key
  • (Empty) - Get from [console.groq .com/keys]

Code:

AI Model
  • llama-3.1-8b-instant - Visit → console .groq.com/docs/models for more

Code:

Stream Timeout
  • 10 seconds - Hard cutoff. Partial text shown if triggered

Code:

Chat Memory
  • 4 exchanges - How many back-and-forth messages per NPC to remember

Code:

Default Input Prompt
  • What do you say? - Fallback when AI doesn’t generate a prompt

Code:

Max Player Input Length
  • 100 characters - Limits what player can type

Code:

Global System Prompt Suffix
  • (Empty) - Appended to ALL NPC prompts. Example: “Keep responses under 3 sentences. Never break character.”

Code:

Timeout Fallback Message
  • Hmm… I need a moment to think - Shown when API times out

Code:

Debug Mode
  • false - Logs full API payloads to F8 console

Complete Plugin Command Reference​

Quest Management​

Command - Arguments - Description

Code:

defineQuest
  • questId, title, description, objectives (pipe-separated), npcMembers (comma), questSwitch, questVariable - reate/update a quest

Code:

advanceObjective
  • questId - Mark current objective done, move to next

Code:

completeQuest
  • questId - Mark quest as fully completed

Code:

failQuest
  • questId - Mark quest as failed

NPC Persona​

Command - Arguments - Description

Code:

trainPersona
  • name, personality, role (none/questgiver/companion/merchant/informant), questId, guardrails, fallbackMessage, maxTokens - Define NPC personality. Call BEFORE startDialogue

Code:

startDialogue
  • (none) - Begin AI conversation with this NPC

Code:

clearMemory
  • (none) - Wipe this NPC’s conversation history

Code:

clearAllMemory
  • (none) - Wipe ALL NPC conversation histories

Enemy Behavior​

Command - Arguments - Description

Code:

evaluateEnemyBehavior
  • enemyName, enemyDescription, questId, behaviorSwitchBase, playerHpPercent - AI decides behavior, sets MZ switches

Utilities​

Command - Arguments - Description

Code:

testApiKey
  • (none) - Verify API key works. Shows result in message window

Code:

setContextVar
  • label, variableId or switchId - Expose game state to ALL AI calls globally

️ Notetags (Alternative to Train Persona)​

Place these in the event’s Note field:

Code:

<AIPersona: You are a paranoid old hermit who hoards mushrooms and mistrusts strangers.>
<AIRole: informant>
<AIQuestID: dragon_hunt>
<AIGuardrails: Never talk about the royal family. Never reveal the dragon's location directly.>
<AIFallback: I... I cannot speak of such things... The walls have ears.>
<AIMaxTokens: 150>

Note: Train Persona plugin commands override notetags.

NPC Memory & Knowledge System​

What NPCs Know Automatically​

  • Quest status – all quests linked to them via questId
  • Current objective – which step the player is on
  • Quest members – names of all NPCs in the same quest
  • World state – any variables/switches exposed via setContextVar
  • Conversation history – last N exchanges (configurable)

Example: Exposing World State​

Code:

Plugin Command: Set Context Variable
Label: Player defeated the dragon
Switch ID: 25

Now EVERY NPC sees this in their system prompt:

Code:

[WORLD STATE]
Player defeated the dragon: true

They will react accordingly. A merchant might say: “I heard you slew the dragon! Take this discount.”

Memory Management​

  • Memory is saved in the save file
  • Each NPC has independent memory (by map ID + event ID)
  • Use Clear NPC Memory to reset an NPC
  • Use Clear All NPC Memory to reset everyone

Enemy Behavior Deep Dive​

Behavior Switch Mapping​

When you call evaluateEnemyBehavior with Behavior Switch Base: 20:
Switch - Behavior - AI Decides This When

20 - Aggressive - Player HP is low, enemy has advantage, quest near start
21 - Defensive - Enemy is wounded, protecting something, buying time
22 - Flee - Enemy is outmatched, mission objective complete, low HP
23 - Reinforce - Enemy is alone vs party, quest climax approaching
24 - Enraged - Quest-specific trigger (e.g., dragon at 30% HP, companion died)

Only ONE switch is ON at a time. Use conditional branches to check them.

Enemy Evaluation Example​

The AI receives this system prompt internally:

Code:

You are an AI Game Master deciding enemy combat behavior.
Enemy: Ashvale Dragon
Description: Ancient red dragon, wounded but enraged.
[QUEST: The Dragon of Ashvale]
Status: ACTIVE
Objectives:
DONE: Talk to Mark
CURRENT: Find the lair
PENDING: Defeat the dragon
Player current HP: 45%
[WORLD STATE]
Player has the Dragon Slayer sword: true

Choose ONE behavior: aggressive / defensive / flee / reinforce / enraged
The AI responds with a single word, and the plugin sets the corresponding switch.

Save File Compatibility​

The plugin saves the following data automatically:

  • _npcMemory – conversation histories
  • _trainedPersonas – all trained NPC personalities
  • _quests – quest states (status, current objective)
  • _ctxVars – exposed context variables

No special handling needed. Save and load normally.

⚠️ Limitations & Warnings​

Issue - Detail
API key visibility - Client-side calls mean the API key is visible in player’s browser. Obfuscation possible but not implemented.
Internet required - Game won’t work offline for AI features. Regular MZ gameplay unaffected.
API costs - You pay for usage. Groq is very cheap (~$0.0002 per dialogue) but not free.
**Steam policy - Must declare AI-generated content in your store listing.

No ongoing development - I made this for fun. It works as-is. I won’t fix bugs or add features.**

​

Troubleshooting​

“API key is empty” error​

  • Check Plugin Manager → GroqNPC → Groq API Key
  • Key should start with gsk_
  • No spaces before or after

Timeout errors​

  • Increase Stream Timeout parameter (10-15 seconds recommended)
  • Switch to llama-3.1-8b-instant model (faster)

No response or weird formatting​

  • Enable Debug Mode and check F8 console
  • Verify your Groq account has credits
  • Test with testApiKey plugin command

NPC doesn’t remember quest​

  • Ensure Quest ID matches exactly (case-sensitive)
  • Call trainPersona BEFORE startDialogue
  • Check that the quest was defined (run defineQuest first)

License & Credits​

MIT License – do literally anything you want.

  • No credit required (but appreciated)
  • No warranty
  • No support

Built with:

  • Groq API – fast LLM inference
  • Groq Models
  • RPG Maker MZ Plugin by Rpx in collaboration with GDSchool

Final Words​

That’s it. Take it, break it, fix it, improve it, sell games with it.

If you make something cool, I’d love to see it. If you don’t, that’s fine too.

It’s Free

Enjoy!
↓FULL CODE ↓
HERE FOR FREE (Maybe I’ll update it if I feel like it and have the time.)

1 Like