NexusCore v1.3 Changelog

Highlights

• Added stable descriptor APIs for dimensions, portals, structures, biomes, AI goals, automation networks, data definitions, recipe families, compatibility reports, balance reports, live reload, performance budgets, and safety policies.
• Added incubating APIs for multiblocks, rituals, progression, authoring tools, simulation dashboards, and brain-style AI descriptors.
• Added generated runtime content installation through NexusRuntimeContent.install(modId).
• Added an always-enabled generated runtime pack so runtime descriptor data can be exposed to Minecraft's resource and dynamic registry loading path.
• Added new /nexus command groups for dumping, validating, inspecting, and simulating v1.3 systems.
• Added v1.3 documentation, cookbook examples, scaffolding docs, migration notes, and new starter templates.
• Removed the embedded example mod projects. Examples now live in docs, Gradle scaffolds, templates, and GameTest scenarios.

---

Added

Dimensions and Portals

• Added NexusDimensions for defining custom dimensions through descriptors.
• Added dimension config profiles, spawn rules, dimension JSON generation, dimension type JSON generation, validation, and debug summaries.
• Added portal descriptors with target dimensions, frame patterns, cooldowns, runtime portal blocks, and safe teleport support.
• Added PortalRuntimeBlock for generated portal block behavior.
• Added validation for duplicate dimension IDs, invalid coordinate scales, unsafe arrival platform radius values, bad portal targets, and invalid cooldowns.

Structures and Jigsaw Support

• Added NexusStructures for structure descriptors, template metadata, placement rules, structure sets, and debug explanations.
• Added structure placement simulation and placement explanation reports.
• Added stable jigsaw pool definitions that write vanilla template-pool JSON into the runtime pack.
• Kept JigsawPoolPreview as a source-compatible alias for older callers.
• Added structure validation for template metadata, required blocks, dimensions, biome selectors, spacing, separation, rarity, and terrain constraints.

Biomes and World Helpers

• Added NexusBiomes for biome descriptor creation.
• Added biome climate settings, environment effects, features, spawns, balance weights, selectors, and biome modifier groups.
• Added support for tag, dimension, and climate selector expressions.
• Added v1.3 world event hook infrastructure through NexusWorldEvent and NexusWorldEventHooks.
• World hooks now route place, break, interact, entity interaction, server tick, and level tick events into multiblock and ritual runtime handlers when available.

AI and Brain Descriptors

• Added NexusAi for goal descriptors and debug reports.
• Added common AI helpers for home positions, territories, patrol routes, path caches, and stuck detection.
• Added GoalLibrary helpers such as guarded-home, follow-owner, and patrol-style goal definitions.
• Added brain AI descriptors with memory, sensor, behavior, and schedule definitions.
• Added AI validation and debug reporting paths.

Automation Networks

• Added NexusAutomation for item, energy, fluid, and mixed transfer networks.
• Added transfer nodes, transfer edges, routing graphs, deterministic route planning, filters, priorities, throughput values, and loop reporting.
• Added automation simulation reports.
• Added built-in runtime automation blocks for item pipes, energy conduits, and fluid pipes.
• Added AutomationPipeBlock as the concrete generated pipe/conduit block implementation.

Data-Driven Definitions and Runtime Content

• Added NexusDataDefinitions for typed data definition registries.
• Added schema validation, docs generation, reload reports, unsafe JSON guards, generated entities, generated worldgen entries, and runtime pack support.
• Added NexusDataDrivenEntity support for data-driven entity definitions.
• Added runtime installation through NexusRuntimeContent.install(modId).
• Added NexusGeneratedPackResources and NexusRuntimeRepositorySource for exposing generated assets and data to Minecraft.
• Added Fabric runtime-pack registration through PackRepositoryMixin and nexuscore.mixins.json.
• Added NeoForge runtime-pack registration through AddPackFindersEvent.

Multiblocks

• Added incubating NexusMultiblocks APIs for fixed and scalable multiblock definitions.
• Added layered patterns, block/tag/state/predicate matchers, optional parts, rotatable and mirrorable layouts, controller metadata, part roles, and preview layers.
• Added scalable multiblock support for bounded builds such as tanks, reactors, shells, and portals.
• Added NexusMultiblockPredicates for common part predicates such as item ports and energy ports.
• Added machine integration descriptors for processing-style multiblocks.
• Added multiblock validation, datagen JSON, debug summaries, export samples, and preview support.

Rituals

• Added incubating NexusRituals APIs for custom world interactions.
• Added center blocks, required structures, item/fluid/energy/entity requirements, weather requirements, time requirements, biome/dimension style requirements, duration, delay, cooldown, lifecycle states, and safety metadata.
• Added NexusRitualActions, NexusRitualEffects, NexusTime, and NexusWeather.
• Added ritual lifecycle runtime tracking for active rituals.
• Added ritual datagen JSON, guide draft metadata, timeline/debug output, and validation reports.

Progression

• Added incubating NexusProgression unlock graph APIs.
• Added progression nodes with dependencies, hidden/optional/repeatable flags, player/team/global scopes, sync metadata, conditions, and unlock actions.
• Added requirements for advancements, items, blocks, entities, rituals, multiblocks, dimensions, structures, machines, and custom checks.
• Added guide page generation, cycle detection, runtime inspection, and debug summaries.

Authoring and In-Game Editor Screens

• Added incubating NexusAuthoring session and editor descriptor APIs.

• Added developer-only authoring sessions, read-only mode, safe export roots, overwrite confirmation metadata, and export logging.

• Added client authoring screen classes:

  • NexusAuthoringScreens
  • NexusAuthoringWorkbenchScreen
  • NexusVisualAuthoringScreen

• Added rendered authoring UI panels for multiblocks, rituals, automation graphs, structures, data definitions, and balance views.

• Added debug workbench entries for authoring tools.

• Added new language keys for the NexusCore Authoring Workbench and authoring editor screens.

Simulation and Balance

• Added NexusBalance for named balance metrics, report generation, and diffing.
• Added deterministic helper scenarios for library-level balance testing.
• Added NexusSimulation for worldgen, economy, combat, diff, and dashboard descriptors.
• Added balance dashboard output and CI-friendly summary reports.

Compatibility Reports

• Added NexusCompatibility for optional integration descriptors.
• Added compatibility matrix reports for JEI, EMI, REI, tooltip providers, equipment APIs, permissions, claims, and mapping docs.
• Added /nexus compat report command support.

Live Reload, Performance, and Safety

• Added NexusLiveReload for safety-gated reload watchers.
• Added development-only and production-safe reload policies.
• Added NexusPerformanceTools for bounded graph caches, cache diagnostics, snapshots, diffs, and budgets.
• Added NexusSafety for centralized automation, teleport, data-driven content, AI, ritual, multiblock, and authoring safety policies.
• Added server/client safety helper classes including ClientActionGuard, SafePaths, and ServerAuthority.

Commands and Debugging

• Expanded the /nexus command tree with v1.3 systems.

• Added dump commands for:

  • dimensions
  • structures
  • biomes
  • AI
  • automation
  • multiblocks
  • rituals
  • progression
  • authoring
  • simulation
  • data definitions
  • compatibility
  • runtime content
  • live reload
  • debug workbench

• Added validation commands for:

  • dimensions
  • structures
  • AI
  • automation
  • multiblocks
  • rituals
  • progression
  • data definitions
  • balance

• Added simulation commands for:

  • automation
  • structure placement
  • worldgen
  • balance

• Added focused command groups for multiblocks, rituals, brain AI, structures, progression, balance dashboards, and compatibility reports.

Gradle Plugin and Scaffolding

• Added v1.3 Gradle scaffolding tasks:

  • nexusCreateDimension
  • nexusCreatePortal
  • nexusCreateStructure
  • nexusCreateBiome
  • nexusCreateAiGoal
  • nexusCreateAutomationNetwork
  • nexusCreateDataDefinition
  • nexusCreateBalanceReport
  • nexusCreateMultiblockMachine
  • nexusCreateScalableMultiblockTank
  • nexusCreateRitualAltar
  • nexusCreateRitualWithMultiblock
  • nexusCreateJigsawStructure
  • nexusCreateBrainBasedMob
  • nexusCreateDataDrivenEntity
  • nexusCreateProgressionTree
  • nexusCreateGuidebookIntegration
  • nexusCreateCompatibilityBridge
  • nexusCreateBalanceSimulationReport

• Added v1.3 validation/report tasks:

  • runNexusDimensionValidation
  • runNexusStructureValidation
  • runNexusAIValidation
  • runNexusAutomationValidation
  • runNexusDefinitionValidation
  • runNexusBalanceDiff
  • validateNexusMultiblocks
  • validateNexusRituals
  • validateNexusBrainAi
  • validateNexusProgression
  • simulateNexusWorldgen
  • simulateNexusRecipes
  • generateNexusSchemas
  • generateNexusGuideDrafts
  • generateNexusBalanceDashboard

• Expanded runNexusValidation to include API checks, binary compatibility, v1.2 source compatibility, docs site generation, v1.3 validation reports, simulations, schemas, guide drafts, and balance dashboards.

Templates and Documentation

• Added v1.3 docs under docs/v1.3/:

  • index.md
  • advanced-creation-systems.md
  • dimensions-structures-biomes.md
  • ai-automation-data.md
  • recipes-compat-ui-live.md
  • balance-testing-diagnostics-performance-security.md
  • gradle-scaffolding.md
  • cookbook.md
  • migration-v1.2-to-v1.3.md

• Added docs/scaffolding-walkthrough.md.

• Updated the generated docs site to include v1.3 in the version switcher.

• Added new template folders:

  • adventure-structures-progression
  • automation-logistics
  • creature-brain-ai
  • datapack-first-content
  • magic-mod-rituals
  • tech-mod-multiblocks

• Retained existing template categories such as minimal item/block, block entity, config-driven, content-heavy, library consumer, test-first, and UI-heavy.

GameTests

• Expanded shared GameTest coverage for v1.3 systems.

• Added tests for:

  • dimension and portal definitions
  • structure placement rules
  • biome and AI helpers
  • automation routing and simulation
  • data definitions, balance reports, live reload, and safety
  • recipe families and compatibility reports
  • runtime installer behavior
  • generated runtime pack resources
  • multiblocks, rituals, and progression
  • authoring descriptors and simulation descriptors

• Fabric and NeoForge GameTest wrappers now register the shared scenarios against the bundled bootstrap structure.

---

Changed

Runtime Initialization

• NexusCore.init() now installs:

  • Architectury lifecycle hooks
  • v1.3 debug workbench tabs
  • /nexus commands
  • world event hooks
  • generated runtime content
  • registry groups

• NexusMod.init() now calls NexusRuntimeContent.install(modId) before registering the owning mod's registry group.

• Generated content is now installed before registry/resource loading so descriptor-backed systems can contribute blocks, entities, assets, data files, dynamic registry JSON, translations, and loot/data definitions.

Module Registry

• Expanded NexusModuleRegistry with v1.3 module metadata.

• Added stable modules for:

  • nexus-world
  • nexus-resource
  • nexus-compat
  • nexus-automation
  • nexus-ai
  • nexus-structure
  • nexus-dimension
  • nexus-debug

• Added incubating modules for:

  • nexus-multiblock
  • nexus-ritual
  • nexus-progression
  • nexus-authoring
  • nexus-simulation

Build and Release Metadata

• Updated the project version from 1.2.0-build.2 to 1.3.0-build.1.
• Resource processing now uses rootProject.modVersion instead of a duplicated literal version string.
• Release checklist now explicitly calls out Java 21 for Gradle execution.
• Release notes now warn against reintroducing the removed embedded example mod.

Source Compatibility Checks

• Replaced checkExampleSourceCompatibility with checkV12SourceCompatibility.
• The new check verifies that important v1.2 public source entry points still exist after removing the example project.
• Checked v1.2 compatibility entry points include machines, transfers, energy, fluids, worldgen, entities, data registries, and recipe viewer displays.

Documentation

• Updated many existing docs to point toward v1.3 systems and the new docs layout.
• Updated README to describe NexusCore v1.3's broader focus.
• Updated architecture, compatibility, config, datagen, debugging, getting-started, item/block, machine, networking, registry, system catalog, testing, and worldgen guides.

---

Removed

• Removed embedded example mod Gradle projects:

  • example-common
  • example-fabric
  • example-neoforge

• Removed the old examples/example-mod source tree from the release archive.

• Removed docs/example-mod-walkthrough.md and replaced the workflow with docs/scaffolding-walkthrough.md, templates, cookbook docs, and GameTest examples.

---

Migration Notes for Mod Authors

Existing v1.2 APIs

The stable v1.2 machine, transfer, energy, fluid, worldgen, entity, resource, recipe viewer, and diagnostics APIs remain available.

Runtime Content Installation

Mods that extend NexusMod do not need extra loader code for v1.3 runtime content. NexusMod.init() now installs runtime content automatically before registry registration.

Mods with custom bootstraps should call:

NexusRuntimeContent.install(modId);
NexusRegistries.registerAll(modId);

in that order.

Machine Preview JSON

Use NexusV13Migrations.migrateMachinePreview to upgrade older preview machine JSON.

The migration:

• renames energyCost to energy
• renames processTicks to ticks
• adds schema_version

Worldgen Helper JSON

Use NexusV13Migrations.migrateWorldgenHelper to upgrade old worldgen helper JSON.

Entity Goal JSON

Use NexusV13Migrations.migrateEntityGoal for older entity goal descriptor data.

The migration renames:

• flags → controls

Balance Profiles

Use NexusV13Migrations.migrateBalanceProfile to add profile versioning to older balancing JSON.

Balance values should move into NexusBalance.BalanceReport metrics when they need to be compared by CI or release validation.

Recipes

Use NexusRecipeFamilies.family when a machine needs advanced recipe grouping, guide indexing, fluid inputs, chance outputs, or recipe viewer documentation.

Automation

The existing side-aware inventory, energy, and fluid transfer APIs remain the low-level transport layer.

Use NexusAutomation.network when you need:

• routing across multiple machines
• item/energy/fluid graph planning
• filters and priorities
• loop detection
• throughput simulation

---

Validation Commands

Recommended release validation:

.\gradlew.bat build runNexusValidation generateReleaseMetadata
.\gradlew.bat :fabric:runGametest
.\gradlew.bat :neoforge:runGametest

Useful focused checks:

.\gradlew.bat runNexusDimensionValidation
.\gradlew.bat runNexusStructureValidation
.\gradlew.bat runNexusAIValidation
.\gradlew.bat runNexusAutomationValidation
.\gradlew.bat runNexusDefinitionValidation
.\gradlew.bat runNexusBalanceDiff
.\gradlew.bat validateNexusMultiblocks
.\gradlew.bat validateNexusRituals
.\gradlew.bat validateNexusBrainAi
.\gradlew.bat validateNexusProgression
.\gradlew.bat simulateNexusWorldgen
.\gradlew.bat simulateNexusRecipes
.\gradlew.bat generateNexusSchemas
.\gradlew.bat generateNexusGuideDrafts
.\gradlew.bat generateNexusBalanceDashboard

---

In-Game Diagnostics

Useful v1.3 commands:

/nexus version
/nexus doctor
/nexus dump dimensions
/nexus dump structures
/nexus dump biomes
/nexus dump ai
/nexus dump automation
/nexus dump multiblocks
/nexus dump rituals
/nexus dump progression
/nexus dump authoring
/nexus dump simulation
/nexus dump data-definitions
/nexus dump compat
/nexus dump runtime-content
/nexus validate dimensions
/nexus validate structures
/nexus validate ai
/nexus validate automation
/nexus validate multiblocks
/nexus validate rituals
/nexus validate progression
/nexus validate data-definitions
/nexus validate balance
/nexus simulate automation
/nexus simulate structure
/nexus simulate worldgen
/nexus simulate balance
/nexus multiblock validate
/nexus multiblock export
/nexus multiblock preview
/nexus ritual list
/nexus ritual validate
/nexus brain dump
/nexus structure simulate
/nexus progression inspect
/nexus balance dashboard
/nexus compat report

---

Notes

• Several large v1.3 systems are intentionally marked incubating, especially multiblocks, rituals, progression, authoring, and simulation.
• The runtime generated pack is now part of the core v1.3 architecture and is required for descriptor-backed dynamic registry/resource data to appear at runtime.
• The old embedded example mod has been intentionally removed. Maintained examples now live in docs, scaffolds, templates, and GameTests.
• v1.3 keeps v1.2 public source entry points available through the new source compatibility verification task.