Contributing

Contributing

Matriochka is open source under the MIT License (code only; models, textures and other art assets are all rights reserved by achedon12). This page explains how the project is built and where to make changes.

Requirements

• Java 25 (the Gradle build targets release 25).
• Python 3 for the content generator.
• The vanilla world generation templates ship in tools/vanilla (26.3) and tools/vanilla_<mc> (the older versions); MC_DATA can point to another extracted data folder.
• Minecraft versions: the code and content are shared; versions/<mc>/ holds what differs (dependencies, the few renamed calls in Mc, McBlocks, McEntities, McClient, McTest, and the world generation in that version's format). After python3 tools/gen.py, run python3 tools/versions.py and python3 tools/check_refs.py; build or test another version with -Pmc=26.2 or -Pmc=26.1.2.
• For the sounds only: numpy and ffmpeg with libvorbis, needed only when a sound recipe changed (see Sounds).

Project layout

tools/              content table and generators
  content.py        single source of truth: worlds, items, blocks, mobs, bosses, structures, quests, achievements, classes
  ui_lang.py        hand-written interface strings (English and French)
  i18n/, translations.py   Spanish, German and Brazilian Portuguese tables, checked against English
  craft.py          hand-painted dolls, cores, Seeds, gear, writings, soils and stations, at any size
  particles.py, atmosphere.py   the mod's particles, and each world's light, fog and floating particles
  hdpack.py, texsheets.py       the Matriochka HD resource pack, and preview sheets of the textures
  bosses_hd.py, boss_moves*.py  the hand-rigged bosses and their attack animations
  anim_preview.py   contact sheets of the boss animations (the images of Boss attacks)
  cues.py           the adaptive music cues: danger theme, heartbeat, stings
  balance.py        balance check against the design's targets (the Balance report)
  modpack.py        builds the Matriochka Pack (.mrpack)
  gen.py            generator: textures, models, lang files, data packs, Content.java
  models.py         GeckoLib model and animation generator
  paint.py          procedural texture painter
  gui.py            interface sprites
  sound.py          sound table: ids, subtitles, world music and ambience
  sfx.py, music.py, synth.py   sound recipes, the folk composer and the synthesizer
  site.py           website data (English and French)
src/main/java       server and common logic: worlds, rules, bosses, stations, karma, classes
src/client/java     renderers, HUD, Journal and station screens
src/gametest/java   showcase client game test
design/             original design notes (French)

Regenerating content

Everything that comes from the content table is generated. Edit tools/content.py (or tools/ui_lang.py for interface text), then run from the repository root:

python3 tools/gen.py

It rewrites the textures, GeckoLib models and animations, the lang files of the nine languages, the dimensions, biomes, structures, advancements and loot tables, and src/main/java/fr/achedon12/matriochka/content/Content.java. Do not edit generated files by hand; your changes would be overwritten.

Hand-written logic lives in Java: recipes in content/Recipes.java, world rules in rules/WorldRules.java, hatching conditions in block/Blocks2.java, the boss attack system in entity/MatrioBoss.java, creature behaviors in entity/MatrioMob.java, item uses in item/MatrioItem.java, commands in command/MatrioCommand.java, config in world/Config.java.

Building and running

./gradlew build              # builds the mod jar into build/libs
./gradlew runClient          # starts a development client
./gradlew runClientGameTest  # showcase test: visits every world, wakes every boss, saves screenshots
./gradlew runClientGameTest -Prules   # the moving worlds: halls, burning lights, gravity columns, shifting ground
./gradlew runClientGameTest -Pstory   # hidden dolls, World 0, endings and the New Cycle
./gradlew runClientGameTest -Pscale   # variants, mutations, effects between the scales and the Maquette
./gradlew runClientGameTest -Pautomation    # station automation with hoppers and comparators
./gradlew runClientGameTest -Pplaythrough   # the whole game in real ticks, from the Guardian to the third ending
./gradlew runClientGameTest -Pvisuals       # every world's atmosphere, the stations by day and night, the particles
./gradlew runClientGameTest -Pmoves         # every boss attack photographed mid-move
./gradlew runClient -Pjei            # a development client with Just Enough Items
./gradlew runClient -Pcompat         # a development client with Sodium, Iris and Mod Menu

The showcase test creates a creative world, opens the Scroll and Journal, opens five stations, then enters worlds 1 to 10 and summons each boss, saving 1920 x 1080 screenshots. It doubles as a smoke test.

Replacing placeholder art

The generated models are placeholders. To replace one:

1. Open src/main/resources/assets/matriochka/geckolib/models/entity/<id>.geo.json in Blockbench (GeckoLib plugin).
2. Keep the animation names the code triggers: the default walk and idle animations, attack.strike for creatures, and attack.charge, attack.slam, attack.cast, attack.strike, misc.phase and misc.rest for bosses.
3. Export the model, animation and texture over the generated files, and remove that entity from the generator if you do not want it overwritten on the next gen.py run.

Translations

All text goes through lang files. English and French come from the en and fr fields of tools/content.py and from tools/ui_lang.py; Spanish, German and Brazilian Portuguese from tools/i18n/<code>.json, checked against English by gen.py. python3 tools/translations.py <code> lists what is missing. See Translations.

Reporting bugs

Open an issue on GitHub with the Minecraft, Fabric Loader, Fabric API and GeckoLib versions, what you did, what you expected and the log. The Roadmap lists the known issues.