FuzzyBot: Updating to match new version of source page

2026-10-22T01:08:26Z

Updating to match new version of source page

← Older revision		Revision as of 01:08, 22 October 2026
Line 190:		Line 190:
	\| <code>hostile_above</code> \|\| Integer \|\| The same, but for an alignment above this value.		\| <code>hostile_above</code> \|\| Integer \|\| The same, but for an alignment above this value.
	\|-		\|-
	\| <code>interaction.min_alignment</code> \|\| Integer \|\| ~~The player needs at least~~ this alignment ~~to talk to~~ the NPC~~. Even if~~ the ~~NPC isn't hostile~~, ~~a low enough~~ alignment ~~still blocks interaction~~. It can also be written directly on the rule, without the <code>interaction</code> wrapper.		\| <code>interaction.min_alignment</code> \|\| Integer \|\| Below this alignment the NPC still talks to the player, but greets them coldly, and its side quests show as locked (saga quests, quests with their own alignment condition and quests already in progress stay available). It can also be written directly on the rule, without the <code>interaction</code> wrapper.
	\|-		\|-
	\| <code>interaction.max_alignment</code> \|\| Integer \|\| The same, but as an upper bound.		\| <code>interaction.max_alignment</code> \|\| Integer \|\| The same, but as an upper bound.
	\|}		\|}

	All four threshold fields are optional: leave out whichever don't apply. Reading the <code>goku</code> entry above as an example: below 25 alignment Goku is hostile; from 25 to 60 he ~~is present~~ but ~~won't talk~~ (the alignment is under the <code>min_alignment</code> of 61); at 61 or more he is friendly and ~~can be talked to~~.		All four threshold fields are optional: leave out whichever don't apply. Reading the <code>goku</code> entry above as an example: below 25 alignment Goku is hostile; from 25 to 60 he still talks to you, but coldly, and his side quests stay locked (the alignment is under the <code>min_alignment</code> of 61); at 61 or more he is friendly and everything is open.

	<code>NpcDispositionService.getRelation()</code> checks the relation in this order:		<code>NpcDispositionService.getRelation()</code> checks the relation in this order:

FuzzyBot: Updating to match new version of source page

2026-10-13T06:26:52Z

Updating to match new version of source page

New page

'''NPC Placement and Alignment''' covers the files that decide where master and trainer NPCs stand and how a player's alignment changes the way each NPC treats them. Two related per-world JSON files do this, both under <code><world save>/dragonminez/npcs/</code>, plus a datapack format for NPCs that live inside structures.

{| class="wikitable"
! File !! What it controls
|-
| <code>placements.json</code> || Where master and trainer NPCs spawn (position, dimension, initial alignment or relation).
|-
| <code>alignment_rules.json</code> || How a '''player's''' alignment affects each NPC's hostility, friendliness and availability for interaction.
|}

Both files load at server start and reload with <code>/dmzreload config</code> (or <code>/dmzreload all</code>); see [[Special:MyLanguage/Reloading and Updating Changes|Reloading and Updating Changes]]. A reload also applies the placements again to every loaded dimension.

{{Note|type=warning|title=Old worlds keep their old files|text=Both files are only written with DragonMineZ's defaults when they are '''missing'''. A world created with an older DragonMineZ version keeps its old files, so it does not get new default entries (for example the v2.2 Otherworld NPCs and their new coordinates). To get the current defaults, delete the file (back it up first if you edited it) and run <code>/dmzreload config</code>.}}

== NPC placement ==
<code>placements.json</code> lists every NPC DragonMineZ places and where.

Source: <code>src/main/java/com/dragonminez/server/world/npc/NPCPlacementManager.java</code>.

<syntaxhighlight lang="json">
{
"schema": 1,
"placements": [
{
"id": "master_roshi",
"entity": "dragonminez:master_roshi",
"dimension": "minecraft:overworld",
"structure": "roshi_house",
"x": 0.0,
"y": 0.0,
"z": 0.0,
"yaw": 225.0,
"pitch": 0.0,
"surface": true,
"relative_to_spawn": false,
"enabled": true,
"override": false
}
]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! What it does
|-
| <code>id</code> || String || Unique placement id. It is tagged onto the spawned entity so DragonMineZ can find and update it later. If two placements share an id, the last one in the file wins (a warning is logged).
|-
| <code>entity</code> || String || Registry id of the entity type.
|-
| <code>dimension</code> || String || Defaults to <code>minecraft:overworld</code>.
|-
| <code>npc_id</code> || String || Only meaningful for <code>dragonminez:quest_npc</code> entities: links to the quest system's NPC id.
|-
| <code>model</code> / <code>texture</code> || String || Only used for <code>quest_npc</code> entities.
|-
| <code>structure</code> || String || If set, <code>x</code>, <code>y</code> and <code>z</code> become an '''offset''' from that structure's origin instead of world coordinates. Valid values: <code>roshi_house</code>, <code>goku_house</code>, <code>elder_guru</code>, <code>timechamber</code>, <code>kamilookout</code>, <code>gero_lab</code>. An unrecognized value falls back to treating <code>x</code>, <code>y</code> and <code>z</code> as raw world coordinates (with a warning in the log).
|-
| <code>x</code>, <code>y</code>, <code>z</code> || Number || World coordinates, or the offset from the structure (see above). Defaults: <code>0.5</code>, <code>64.0</code>, <code>0.5</code>.
|-
| <code>yaw</code>, <code>pitch</code> || Number || Facing direction in degrees.
|-
| <code>surface</code> || Boolean || If <code>true</code>, snaps Y to the terrain surface at load time instead of using the given Y.
|-
| <code>relative_to_spawn</code> || Boolean || If <code>true</code>, adds the world's spawn point to <code>x</code> and <code>z</code> (applied after any structure offset).
|-
| <code>enabled</code> || Boolean || If <code>false</code>, this placement is skipped entirely.
|-
| <code>override</code> || Boolean || If <code>true</code>, the entity is always respawned, even if one already exists for this <code>id</code>. Otherwise an existing entity is just updated in place.
|-
| <code>alignment</code> || Integer (0–100) || Optional alignment for this specific NPC: above 60 it is friendly, from 41 to 60 neutral, and 40 or less hostile (unless an alignment rule makes it hostile first, see below).
|-
| <code>relation</code> || String || Optional override for this instance (<code>HOSTILE</code>, <code>NEUTRAL</code> or <code>FRIENDLY</code>), stored on the entity itself instead of being looked up from the alignment rules.
|}

Unknown keys are reported in the JSON load report.

=== Default placements ===
The default file actively spawns these NPCs:

{| class="wikitable"
! Placement id !! Entity !! Where
|-
| <code>master_roshi</code> || <code>dragonminez:master_roshi</code> || Roshi's house
|-
| <code>master_goku</code> || <code>dragonminez:master_goku</code> || Goku's house
|-
| <code>master_karin</code>, <code>master_dende</code>, <code>master_popo</code> || <code>dragonminez:master_karin</code>, <code>master_dende</code>, <code>master_popo</code> || Kami's Lookout
|-
| <code>master_gero</code> || <code>dragonminez:master_gero</code> || Gero's lab
|-
| <code>master_guru</code> || <code>dragonminez:master_guru</code> || Elder Guru's house (Namek)
|-
| <code>master_kaiosama</code> || <code>dragonminez:master_kaiosama</code> || Otherworld, <code>54.5 299 1031.5</code>
|-
| <code>master_toribot</code> || <code>dragonminez:master_toribot</code> || Otherworld, <code>50.5 298 1030.5</code>
|-
| <code>master_enma</code> || <code>dragonminez:master_enma</code> || Otherworld, <code>0.5 150 17.5</code>
|-
| <code>master_baba</code> || <code>dragonminez:master_uranai</code> || Otherworld, <code>9.5 150 3.5</code>
|-
| <code>master_grandkai</code> || <code>dragonminez:master_grandkai</code> || Otherworld, <code>-30.5 150 12.5</code>
|-
| <code>npc_hell_ogre</code> || <code>dragonminez:quest_npc</code> (<code>npc_id</code> <code>hell_ogre</code>) || Otherworld, <code>9.5 150 16.5</code>
|-
| <code>master_otherworld_announcer</code> || <code>dragonminez:master_otherworld_announcer</code> || [[Special:MyLanguage/Otherworld Tournament|Otherworld Tournament]] grounds, <code>-25.5 352 -1164.5</code> (only placed once the tournament grounds have been built)
|}

=== Quest NPCs and master NPCs ===
Quest NPCs (Bulma, Krillin, Yamcha, Tien, Piccolo, Gohan, Vegeta, Trunks, Chi-Chi, Videl, Shin and the Namek Elder) appear in the default file too, but with <code>"enabled": false</code>: they are no longer spawned at runtime through this system. They are baked directly into the structure NBT, so they live at fixed, hand-placed spots instead of piling up at the world spawn. Their entries here are for reference only. NPCs added to a structure after its NBT was made come from [[Special:MyLanguage/NPC Placement and Alignment#Structure NPCs|structure NPC files]] instead (Chi-Chi in Goku's House is one).

The Otherworld NPCs (<code>master_kaiosama</code>, <code>master_enma</code>, <code>master_baba</code>, <code>master_toribot</code>, <code>master_grandkai</code>, <code>master_otherworld_announcer</code> and <code>npc_hell_ogre</code>) always force <code>override: true</code> internally, whatever the file says, since they need to exist reliably in a generated dimension. See [[Special:MyLanguage/Otherworld|Otherworld]].

== Structure NPCs ==
Structure NPC files place NPCs '''inside''' a DragonMineZ structure without editing its <code>.nbt</code> file. Unlike the files above, these are '''datapack''' files: <code>data/<namespace>/structure_npcs/*.json</code>, one per structure, loaded with the datapacks (and by <code>/reload</code>).

<syntaxhighlight lang="json">
{
"structure": "dragonminez:goku_house",
"npcs": [
{
"id": "npc_chi_chi",
"entity": "dragonminez:quest_npc",
"npc_id": "chi_chi",
"model": "saga_videl",
"texture": "saga_chichi",
"pos": [67.5, 5.0, 50.5],
"yaw": 90.0
}
]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Required !! What it does
|-
| <code>structure</code> || Yes || Id of the structure the NPCs belong to.
|-
| <code>id</code> || Yes || Unique id of this NPC inside the structure. It is also the tracking key, so don't rename it once worlds use it.
|-
| <code>entity</code> || Yes || Entity type to spawn (for example <code>dragonminez:quest_npc</code> or a master's entity id).
|-
| <code>npc_id</code> || No || Quest NPC id, for <code>dragonminez:quest_npc</code>.
|-
| <code>model</code>, <code>texture</code> || No || Model and texture names for quest NPCs.
|-
| <code>template</code> || No || Which template of the structure the position is relative to, for structures made of several pieces.
|-
| <code>pos</code> || Yes || Position '''relative to the structure's template''', so it stays right whatever rotation the structure spawned with.
|-
| <code>yaw</code> || No || Facing, also relative to the template (default <code>0</code>).
|-
| <code>alignment</code>, <code>relation</code> || No || Initial alignment and relation, as in <code>placements.json</code>.
|}

Each NPC spawns '''once''' per generated structure when its chunk loads, including structures that were generated before the file existed, and the spawn is remembered: an NPC that dies doesn't come back.

To get the coordinates, stand where the NPC should be and run <code>/dmzstructure here</code>: it prints the structure, its template and your position and yaw relative to the template, with a '''Copy NPC JSON''' button that copies a ready-made entry. <code>/dmzstructure npcs</code> lists the NPCs of the structure you are in and whether each one has spawned yet. Both commands need the <code>dragonminez.dmzstructure</code> permission (see [[Special:MyLanguage/Permissions|Permissions]]).

== NPC alignment rules ==
{{See also|Alignment|Masters}}
<code>alignment_rules.json</code> decides how each NPC reacts to the player's alignment.

Source: <code>src/main/java/com/dragonminez/common/alignment/NpcAlignmentRules.java</code>.

<syntaxhighlight lang="json">
{
"npcs": {
"goku": {
"default_relation": "FRIENDLY",
"interaction": { "min_alignment": 61 },
"hostile_below": 25
},
"gero": {
"default_relation": "NEUTRAL",
"interaction": { "max_alignment": 60 }
}
}
}
</syntaxhighlight>

The keys in <code>npcs</code> are NPC ids '''with any namespace stripped''' (<code>dragonminez:roshi</code> becomes the key <code>roshi</code>).

{| class="wikitable"
! Field !! Type !! What it does
|-
| <code>default_relation</code> || <code>HOSTILE</code> / <code>NEUTRAL</code> / <code>FRIENDLY</code> || Base relation when none of the thresholds below overrides it. Defaults to <code>NEUTRAL</code>.
|-
| <code>hostile_below</code> || Integer || If the player's alignment is below this value, the NPC turns hostile regardless of <code>default_relation</code>.
|-
| <code>hostile_above</code> || Integer || The same, but for an alignment above this value.
|-
| <code>interaction.min_alignment</code> || Integer || The player needs at least this alignment to talk to the NPC. Even if the NPC isn't hostile, a low enough alignment still blocks interaction. It can also be written directly on the rule, without the <code>interaction</code> wrapper.
|-
| <code>interaction.max_alignment</code> || Integer || The same, but as an upper bound.
|}

All four threshold fields are optional: leave out whichever don't apply. Reading the <code>goku</code> entry above as an example: below 25 alignment Goku is hostile; from 25 to 60 he is present but won't talk (the alignment is under the <code>min_alignment</code> of 61); at 61 or more he is friendly and can be talked to.

<code>NpcDispositionService.getRelation()</code> checks the relation in this order:
# A <code>relation</code> set on the placement (<code>placements.json</code>) wins.
# The rule's <code>hostile_below</code> and <code>hostile_above</code> thresholds.
# An <code>alignment</code> set on the placement.
# The rule's <code>default_relation</code>.

=== Master NPCs ===
For '''master and trainer NPCs''' the rule file decides hostility, but their alignment gate is a fixed rule instead of <code>interaction</code>: masters can always be talked to, but [[Special:MyLanguage/Goku|Goku]], [[Special:MyLanguage/Gohan|Gohan]], [[Special:MyLanguage/King Kai|King Kai]], [[Special:MyLanguage/Old Kai|Old Kai]], [[Special:MyLanguage/Master Roshi|Roshi]] and [[Special:MyLanguage/Krillin|Krillin]] only unlock their '''Skills''', '''Train''' and new quests at an alignment of at least '''61''', and [[Special:MyLanguage/Cell|Cell]] and [[Special:MyLanguage/Frieza|Frieza]] at '''40 or less'''. Every other master has no alignment gate. See [[Special:MyLanguage/Masters|Masters]].

=== NPC ids covered by default ===
The default file covers <code>goku</code>, <code>roshi</code>, <code>karin</code>, <code>guru</code>, <code>dende</code>, <code>popo</code>, <code>kingkai</code>, <code>gero</code>, <code>enma</code>, <code>baba</code>, <code>toribot</code>, <code>grandkai</code>, <code>otherworld_announcer</code>, <code>bulma</code>, <code>krillin</code>, <code>yamcha</code>, <code>tien</code>, <code>chiaotzu</code>, <code>gohan</code>, <code>trunks</code>, <code>chi_chi</code>, <code>videl</code>, <code>namek_elder</code>, <code>shin</code>, <code>piccolo</code> and <code>vegeta</code>.
* Most default to <code>FRIENDLY</code> with <code>min_alignment: 41</code> (or <code>61</code> for Goku, Guru, Dende, King Kai and the Namek Elder) and <code>hostile_below: 25</code>.
* <code>gero</code> defaults to <code>NEUTRAL</code> with <code>max_alignment: 60</code>.
* <code>enma</code>, <code>baba</code>, <code>toribot</code>, <code>grandkai</code>, <code>otherworld_announcer</code> and <code>vegeta</code> default to <code>NEUTRAL</code> with no thresholds.
* <code>piccolo</code> defaults to <code>NEUTRAL</code> with its own thresholds (<code>min_alignment: 41</code>, <code>hostile_below: 20</code>).

== Reload and validate ==
# Edit the files under <code><world save>/dragonminez/npcs/</code>.
# Validate the JSON syntax (see [[Special:MyLanguage/How to JSON|How to JSON]]).
# Run <code>/dmzreload config</code> (or <code>/dmzreload all</code>); see [[Special:MyLanguage/Reloading and Updating Changes|Reloading and Updating Changes]].
# Check that the NPC spawned or moved as expected, and that hostility and interaction based on alignment behave as configured (test at a couple of alignment values if you can).

{{Navbox Modding}}

NPC Placement and Alignment/en - Revision history

FuzzyBot: Updating to match new version of source page

FuzzyBot: Updating to match new version of source page