DATAPACKS
SOULs and trials are datapacks: one small JSON file each, no code needed. Put the pack in a world's datapacks folder, or pick it under Data Packs when you create a world.
SOULs
A SOUL is one file, data/<namespace>/soulverse/human_soul/<id>.json: its name, its colour, its place on the ring, its quirks and, if you like, a sound of its own. It appears in character creation, in names, hearts and the SV menu, exactly like Soulverse's own; the fourteen Additional Souls are made this way.
data/mysouls/soulverse/human_soul/hopeful.json
{
"name": { "text": "Hopeful" },
"color": "#FF8800",
"order": 200,
"select_sound": "mysouls:soul.select.hopeful",
"quirks": ["soul_sharing"],
"priority": 0
}
| Field | |
|---|---|
name | Required. Its name, a text component ({"text": …} or {"translate": …, "fallback": …}). |
color | Required. Its colour, #RRGGBB. Keep it clearly apart from the SOULs nearest it in colour. |
order | Required. Its place on the ring: Soulverse's own go round the colour wheel, red (0) to pink (95). |
passive | Its line under its name on the ring. |
quirks | The quirks every player with this SOUL has, by id (each quirk's id is on its page here). |
select_sound | A sound event played when it is chosen, from a resource pack. |
selectable | false keeps it out of character creation and Random; admins can still give it. |
priority | When two packs have a SOUL with the same id, the higher one is used (Soulverse's own are 0). |
The full guide, with templates to download and a pack made for you:
- Make your own SOUL: every field explained, step by step, with the data pack and sound pack templates.
- Data Pack Generator: make your SOULs by picking, with their sound, and download the packs ready to use. It makes trials too (the Trials tab at the top).
Trials
A trial is one file, data/<namespace>/soulverse/trial/<id>.json. Trials are read again on /reload; a file with a mistake is left out with a warning in the server log, and the others load as usual. See Trials for how they play.
Don't feel like writing JSON? The Trial Generator builds the pack for you: name, flavour, reward, emblem, group and every step, then download it.
Where the files go
<your pack>/
pack.mcmeta
data/<namespace>/soulverse/trial/<id>.json
The trial's id is <namespace>:<id>, for example mytrials:four_titans. Trials are read again on /reload. A file with a mistake is left out with a warning in the server log ([Soulverse] Trial … left out: …), and the other trials load as usual.
A trial
{
"name": {"translate": "mytrials.trial.four_titans", "fallback": "Trial of the Four Titans"},
"flavour": "Those who fell the titans may bend time.",
"reward": "rewind_step",
"reveal_reward": false,
"icon": "minecraft:clock",
"ordered": false,
"steps": [
{"id": "dragon", "type": "kill", "entity": "minecraft:ender_dragon", "text": "Slay the Ender Dragon"},
{"id": "wither", "type": "kill", "entity": "minecraft:wither", "text": "Slay the Wither"}
]
}
| Field | ||
|---|---|---|
name | required | A text component: a plain string, {"text": …} or {"translate": …, "fallback": …} |
flavour | optional | A line shown in quotes at the bottom of its panel (flavor works too) |
reward | optional | A quirk id, or a list of them, given when every step is done (as an admin would give it) |
reveal_reward | optional, false | While false, the reward shows as ??? until the trial is done |
icon | optional | The trial's emblem: a texture id (soulverse:trial/four_titans = assets/soulverse/textures/trial/four_titans.png, see "Emblems"), an item id (minecraft:clock), or quirk:<id> for that quirk's picture. Without one, the tile shows the reward's picture when it is named, else an hourglass |
ordered | optional, false | When true, the steps count only in their order: only the first step not done yet moves on |
steps | required | At least one step |
group | optional | An id (mytrials:paths): the trial is one path of a group, see "Groups" |
A step
Every step has an id (unique within the trial; progress is kept under it), a type, a text (a text component) and a count (how many times; 1 if left out). The other fields depend on the type:
type | Fields | What counts |
|---|---|---|
kill | entity: an id, a #tag or a list (none: any mob); at_night (only while it is dark outside); dimension: an id or a list; by_player_only (only the player's own blow or shot, not a kill they only get the credit for) | A mob of that kind killed by the player |
mine | block: an id, a #tag or a list | A block broken by the player |
advancement | advancement: its id | The advancement made (also one made before the trial existed, counted when they join) |
visit_biome | biomes: a list, a #tag, or "all"; with "all", dimensions (default the Overworld) | Distinct biomes stood in (checked every second). count is how many different ones; left out, every biome named (or, with "all", every biome those dimensions can make) |
tame | entity: an id, a #tag or a list (none: any) | An animal tamed |
trade | professions: a list, a #tag or "all" (every profession but none and nitwit); none: any trader | Trades with distinct professions (a wandering trader counts as minecraft:wandering_trader). Left out, count is every profession named |
custom | key: any string | Whatever Java code counts with Trials.advance(ServerPlayer, "<key>", amount) |
Groups: choosing a path
Trials with the same group are paths to choose between. Once a player has finished as many trials of a group as the server allows (trials.rewards_per_group, 1 by default), every other trial of that group closes to them for good:
- its progress stops counting
- its tile stays in their F4 list, greyed with a lock and "Path closed", so they see what they gave up
Finishing decides; claiming doesn't. A finished trial of a group does not give its reward by itself. It stays "Complete, unclaimed" with a CLAIM button in the F4 list, and the player may claim it whenever they like. Claiming asks once (the quirk, its words, CLAIM / NOT YET) and the reward is theirs for good. When a path has only its last step left, its panel and the step's line warn: "Finishing this path closes the others to you forever."
Trials without a group give their reward the moment they are done and have no limit.
Emblems
A trial's own picture is a 32×32 PNG at assets/<namespace>/textures/trial/<name>.png, named in the trial as "icon": "<namespace>:trial/<name>". Ship it in a resource pack (or a mod's assets) next to the datapack. Draw it in pixel art; the game draws it crisp at the tile's size, in three looks:
- in progress: dim, filling with its colours from the bottom as the trial is done
- complete: in full colour with a soft gold glow
- path closed: dark grey with a small lock
A player whose game doesn't have the picture sees the hourglass instead. Soulverse has five of its own, used by its own trials: soulverse:trial/smiths_oath, hoard, kinship, deep_dark and four_titans (made by tools/generate_trial_emblems.py).
For mod authors
nl.kirbee.soulverse.trial.Trials.advance(ServerPlayer player, String key, int amount) moves every custom step with that key on by amount for the player. Call it from anything you want to count.
For server admins
- The SV menu's Trials tab (
soulverse.trials.viewto see it,soulverse.trials.editto change it; operators by default) has:- the server's switch for all trials (
trials.enabled) and "Paths per Group" (trials.rewards_per_group, 1–10) - every trial the datapacks have, with a search bar; a trial switched off is greyed
- for the one picked: its switch, flavour, reward (with arrows to set the datapack's, none or any quirk), the datapack it comes from, its group, how many players have begun and finished it, each step's count (slider or typed), and "Reset for Everyone"
- the server's switch for all trials (
- These changes are kept in
config/soulverse/trials.json(the world's folder in singleplayer) by trial id:enabled,counts(step id to count) andreward(""none). They are laid over the datapacks' trials at once, without a restart. A switched-off trial counts nothing, is hidden from players' F4 lists (their progress is kept) and gives nothing.
trials.enabled(on by default) is on the Trials tab, not the Server tab. When it is off, nothing counts and the F4 list has no Trials tab.- A player's page in the SV menu has a Trials button (
soulverse.players.trials). It opens a page listing every trial the server has, with their progress in each and three buttons:- Grant: every step done and the reward given (for a group's path only while the group's limit allows; hold Shift for "Grant (force)" to go past it)
- Reset: their progress forgotten, back to the first step; resetting a finished path reopens its group's others. When the reward was given there are two buttons: Reset, take quirk and Reset, keep quirk
- Reveal: the first step marked done for them
- The same as commands:
/sv players trial grant|reset|reveal|progress <player> <trial>, withgrant … force(past a group's limit) andreset … take(the reward taken back too). Claims are written in the player's log. - Progress is in each player's file,
config/soulverse/<username>.json, undertrials. For each trial it holdssteps(step id to count),seen(the distinct biomes or professions),completed_atandclaimed.
The template
data/mytrials/soulverse/trial/four_titans.json
{
"name": {"translate": "mytrials.trial.four_titans", "fallback": "Trial of the Four Titans"},
"flavour": "Those who fell the titans may bend time.",
"reward": "rewind_step",
"reveal_reward": false,
"icon": "minecraft:clock",
"ordered": false,
"steps": [
{"id": "dragon", "type": "kill", "entity": "minecraft:ender_dragon", "text": "Slay the Ender Dragon"},
{"id": "wither", "type": "kill", "entity": "minecraft:wither", "text": "Slay the Wither"},
{"id": "warden", "type": "kill", "entity": "minecraft:warden", "text": "Slay a Warden", "by_player_only": true},
{"id": "guardian", "type": "kill", "entity": "minecraft:elder_guardian", "text": "Slay an Elder Guardian"}
]
}
data/mytrials/soulverse/trial/wanderer.json
{
"name": "The Wanderer",
"flavour": "Go where the maps end.",
"reward": ["sneaky_peek"],
"reveal_reward": true,
"icon": "quirk:sneaky_peek",
"ordered": true,
"steps": [
{"id": "nether", "type": "advancement", "advancement": "minecraft:story/enter_the_nether", "text": "Enter the Nether"},
{"id": "diamonds", "type": "mine", "block": "#minecraft:diamond_ores", "count": 5, "text": "Mine five diamond ores"},
{"id": "night", "type": "kill", "entity": "#minecraft:undead", "count": 20, "at_night": true, "dimension": "minecraft:overworld", "text": "Slay 20 undead at night"},
{"id": "wolves", "type": "tame", "entity": "minecraft:wolf", "count": 2, "text": "Tame two wolves"},
{"id": "traders", "type": "trade", "professions": "all", "text": "Trade with every kind of villager"},
{"id": "biomes", "type": "visit_biome", "biomes": "all", "dimensions": ["minecraft:overworld"], "text": "Visit biomes"}
]
}