Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,9 @@ jobs:
if-no-files-found: error
retention-days: 30
path: |
build/libs/OreSpawn-4.1.6.111021.jar
build/libs/OreSpawn-4.1.6.111021-sources.jar
build/libs/OreSpawn-4.1.6.111021-javadoc.jar
build/libs/OreSpawn-4.1.7.111021.jar
build/libs/OreSpawn-4.1.7.111021-sources.jar
build/libs/OreSpawn-4.1.7.111021-javadoc.jar
build/release/SHA256SUMS
CHANGELOG.txt

Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
OreSpawn 4.1.7.111021
- Add chunk surveys, rule explanations and guarded clear/undo tools for test worlds.
- Keep clear and undo previews valid when protected leaves finish a normal decay check.
- Add optional geological formations and preserve provider template overrides.
- Keep formations out of native structure areas, including woodland mansions.
- Keep completed retrogen revisions through repeated saves and server restarts.
- Retain saved ore rules without enabling duplicate provider defaults.

## 4.1.6.111021

- Fix duplicate ore generation when an OreSpawn 1 world is moved without its converted provider file. Keep imported rules and saved choices, and back up the profile before removing a duplicate. Leave edited rules for review.
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ It gives mods and modpacks one place to configure ores, deposit shapes, optional
rock strata and geomes, provider-owned underground fluid deposits, biome
palettes and world materials, flat bedrock, and bounded ore retrogen.

This branch builds target-qualified version `4.1.6.111021`: the OreSpawn 4.1.6
This branch builds target-qualified version `4.1.7.111021`: the OreSpawn 4.1.6
feature set for Minecraft 1.11.2 and Forge. It adds stable generation identity,
non-loading geology sampling, per-resource background control, existing-world
provider merge policy, an Ore Sources arbiter for equivalent provider ores, a
Expand All @@ -31,6 +31,10 @@ translation.
If you already have an OreSpawn 4 provider override, importing an older config
leaves it in place. The upgrade report tells you which files were kept.

Recognised provider rule renames keep the saved ore settings and add the modern
rule as a disabled, editable alternative, avoiding an extra generation pass.
See [retained provider rules](docs/MIGRATION.md#retained-provider-rules).

This is not the unrelated mod that adds mobs and dimensions under the same
name.

Expand Down Expand Up @@ -186,3 +190,7 @@ Public developer and AI integration guidance lives in `docs/` and is included
in the built jar.

OreSpawn is licensed under LGPL-2.1.

## Distribution tools and formations

Use the [admin tools guide](docs/ADMIN_TOOLS.md) for loaded-chunk surveys and guarded clear/undo. The [formation guide](docs/ROCK_FORMATIONS.md) explains optional provider-defined rock formations. Existing worlds do not adopt formations automatically.
5 changes: 3 additions & 2 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -211,8 +211,8 @@ tasks.register('verifyDocumentationParity') {
dependsOn tasks.named('processResources')
doLast {
List<File> tracked = trackedDocumentationFiles()
if (tracked.size() != 20) {
throw new GradleException("Expected 20 tracked documentation files, found ${tracked.size()}")
if (tracked.size() != 22) {
throw new GradleException("Expected 22 tracked documentation files, found ${tracked.size()}")
}
tracked.each { File source ->
String relative = documentationRelativePath(source)
Expand Down Expand Up @@ -286,6 +286,7 @@ apply from: 'gradle/verification/support.gradle'
apply from: 'gradle/verification/legacy-and-migration.gradle'
apply from: 'gradle/verification/client-and-benchmark.gradle'
apply from: 'gradle/verification/packaged-forge.gradle'
apply from: 'gradle/verification/admin-tools.gradle'
apply from: 'gradle/release/artifacts.gradle'
apply from: 'gradle/release/publishing.gradle'
apply from: 'gradle/ide/eclipse.gradle'
135 changes: 135 additions & 0 deletions docs/ADMIN_TOOLS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Admin and distribution tools

Use these tools in a disposable Creative world while tuning a pack. Surveys
do not generate terrain or enable OreSpawn's vanilla-ore management. Clearing
is different: it changes saved blocks, including matching player-placed rocks.

## Measure what actually generated

```
/orespawn help
/orespawn status verbose
/orespawn chunk
/orespawn chunk -2 3
/orespawn survey 1
/orespawn survey 2 --y 0 48 --block minecraft:redstone_ore
/orespawn survey 0 --center -2 3 --block minecraft:stone@3
/orespawn explain minecraft:redstone_ore 100 20 -40
/orespawn retrogen status
/orespawn jobs
/orespawn jobs <job-id>
/orespawn cancel <job-id>
```

New diagnostic commands require permission level 2. Ordinary `status` remains
available without operator permission. Existing `reload`, `retrogen [radius]`
and `dump-biomes` commands keep their behaviour. `retrogen status` never queues
work, enables retrogen or writes a generation marker. Its completed flag is
session bookkeeping, not a claim about a chunk's complete history.

Chunk coordinates are block coordinates divided by 16, rounding down, including
negative coordinates. Without coordinates, commands use the player's chunk;
the console uses Overworld spawn. Shared options are `--center <chunkX chunkZ>`,
`--dimension <loaded-numeric-or-namespaced-ID>`, `--y <min max>` and the survey
filter `--block <namespace:block[@metadata]>`. Heights are inclusive. Radius
defaults to 1 and is limited to 8: a square of `(2 * radius + 1)` chunks per side.

Only chunks already loaded are visited. The tool records skipped chunks and
chunks that unload during a scan. A partial report is not a complete regional
sample. Scans happen over a recorded interval, not at one atomic world instant.
For a fair comparison, use the same seed, dimensions, coordinates, height range
and coverage, and avoid mining or construction while collecting the sample.

Reports are stored in the world's `orespawn/diagnostics/reports/<job-id>/`.
Long chat summaries end in `...`; the saved reports are not shortened.
Check `jobs <job-id>` for export completion or I/O failure. JSON records block
states and categories, exact Y levels, biome columns, per-chunk counts, coverage
and the active profile fingerprint. CSV files provide the same count tables.
Total sampled volume includes air; non-air volume is reported separately. A
block filter restricts both those denominators to the matching sample.

Known ores come from native identities, configured outputs and exact Ore
Dictionary registrations. Blocks are counted once even if several providers
share them. All observed states are exported, including unclassified blocks.
Configured fluid outputs are listed separately from ores. Reports do not
identify which mod historically placed a block or declare that a distribution
is statistically correct from a small sample.

`explain` uses OreSpawn's actual baked placement budget, host tests and
chunk-centre biome checks. Frequency means expected attempts per chunk, not
guaranteed blocks. Weighted host tests, random geometry, exposure rolls and
private extension checks still affect results. A rock under the cursor today
is not necessarily the host that existed during original generation. Chunk
geology information is labelled as a current base-geology prediction, not
saved formation provenance.
`chunk` also records observed block states down the centre column, every 16
blocks and at the selected range's endpoints. These sparse samples are not a
whole-chunk count; use `survey 0` for that.

## Expose one chunk, with a way back

```
/orespawn clearchunk --center -2 3
/orespawn clearchunk confirm <preview-token>
/orespawn undo <backup-id>
/orespawn undo <backup-id> confirm <undo-preview-token>
/orespawn jobs backups
```

Clearing and undo require permission level 4. Player operators must be Creative
or Spectator; clearing is refused while a Survival/Adventure player occupies
the target chunk. Keep the surrounding lighting area loaded. The aliases
`/clearchunk` and `/clearchunks` are registered only if another mod has not
claimed them. Both mean one chunk, not a region.

The first command only scans and prints a preview; no blocks change yet.
Review the coordinates, height range and removal count, then open chat (T by
default) and click **Confirm clearing**. That click sends the confirmation
command. **Cancel** dismisses the preview without changing blocks; **Details**
opens the job report. Hover over a link to see its exact command. The commands
above also work when typed, and the server console prints a copyable command.

After clearing, the **Undo…** link starts a restoration preview, not an
immediate restore. Review it and click **Confirm undo** to restore the blocks.
Tokens expire after 120 seconds and belong to their operator and snapshot.
A changed profile or block snapshot requires a new preview. The decay-check
flag on protected vanilla leaves is ignored: Minecraft updates it while checking
healthy trees, without changing the blocks being cleared. Removed leaves,
different leaf types and other block edits still invalidate the preview. Reports
and backups keep exact states, including leaves configured as removable terrain.
There is no immediate, unconfirmed clear mode.

Clearing removes recognised native/provider host rocks and background fluids.
Known ore outputs, configured fluid deposits, bedrock, tile entities and
unrecognised blocks are protected. Protection wins if a state is both an ore
and a host. When a configured deposit uses ordinary water or lava, the same
fluid elsewhere is protected too: there is no reliable historical provenance.

Before the first write, the tool writes, flushes and verifies an immutable
checksummed journal under `orespawn/diagnostics/backups/<backup-id>/`.
If that fails, no clearing occurs. Backups are not automatically deleted.
They remain on disk after restarts; `jobs backups` gives their directory.
Journals record the Minecraft version and are not interchangeable with backups
from other Minecraft versions, whose height and block-state encodings differ.

Undo validates every recorded state and checks the current blocks before
restoring anything. Already-restored cells are harmless; other intervening
edits cause a conflict rather than being overwritten. Work can be cancelled
or interrupted, so always inspect its final job status. A partial edit remains
recoverable from its original journal and never resumes by itself after restart.
Cancellation stops block writes, then finishes bounded lighting cleanup. If
the chunk or its lighting area unloads, the report records the interruption
and the chunk is marked for native relighting instead of claiming completion.

Undo restores recorded block states, not entity movement, elapsed time, mining
or changes made elsewhere. Fluids from outside the selection can later flow
back in. It is not a substitute for a full world backup.

One server job runs at a time, yielding after 16,384 block visits or a 4 ms
cooperative budget. File output runs separately and touches no live world.
No command expands the loaded chunk set to finish a report or an edit.
Reports stop with an explicit error above 500,000 count-table rows; individual
sidecars are limited to 32 MiB. Reduce the area or height range if you hit a
limit. Existing backups are never removed to make room.
The file-worker backlog is capped at 32 tasks. A full queue reports failure;
it never runs file output on the server thread or starts an unbacked edit.
8 changes: 8 additions & 0 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,14 @@ or `host_tags` entry. Optional `biome_ids`, `excluded_biome_ids`,
Only ore rules with `retrogen:true` participate. Terrain strata are never
retro-generated.

Completed revisions survive chunk saves and server restarts, including time
spent with retrogen disabled. Changing settings alone does not mark a new
revision as complete. A different revision, `force:true`, or the manual
retrogen command can deliberately run another pass. Keep force off for normal
use. This repair cannot identify or remove extra ores placed by older builds,
or reconstruct completion markers those builds already lost; back up your save
before enabling retrogen.

`flat_bedrock.enabled` and `flat_bedrock.retrogen` are off by default.
`layers` is 1-5 and `dimensions` is an array of full dimension IDs.

Expand Down
36 changes: 36 additions & 0 deletions docs/MIGRATION.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,41 @@
# Migration

## Retained Provider Rules

An older profile can keep an ore rule after its provider renames that rule.
OreSpawn must not add a second generation pass just because the ID changed.
The merge recognises OreSpawn's imported `orespawn:legacy/<provider>/...`
rules and the following exact Base Metals replacements:

- `basemetals:legacy/<material>_ore` to `basemetals:ore/<material>` for
coldiron, adamantine, starsteel, tin, lead, zinc, silver, mercury, nickel
and platinum.

A match needs one saved rule and one provider candidate with the same single
output, default metadata, and dimension/selector and effective placement-channel
footprint. Conflicting provider ownership, mixed outputs, different deep outputs
and ambiguous matches are not treated as replacements. A generic mod's
`legacy/` name is not enough evidence.

For a recognised match, the missing modern rule is added as a complete,
disabled alternative. The saved rule keeps its rates, hosts, heights, pattern,
enablement and source choices, including disabled and zero-rate settings.
Fresh worlds still use the provider's normal defaults.

You can enable the alternative in the ore settings. Later merges retain that
choice, existing modern rules and recorded deletions. A recorded deletion of
one of the historical Base Metals IDs also leaves its mapped replacement
disabled. Deleted imports without an exact mapping are not guessed from their
names.

This repair does not automatically remove an already-saved historical
Base Metals/modern pair: both may have been selected deliberately. Review
ambiguous or previously affected profiles before changing their choices.
It does not alter generated chunks, public APIs or saved formats.

The existing OS1 import repair still applies when its own provenance and
backup checks are met; this rule-rename check does not replace it.

## OreSpawn 3 Compatibility On Minecraft 1.11.2

This branch ships a deprecated compatibility bridge for existing OreSpawn 3
Expand Down
4 changes: 4 additions & 0 deletions docs/PLAYER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,5 +182,9 @@ For a dedicated server, copy the whole world including that file and install
the same mods. Alternatively, place a prepared global profile at
`config/orespawn-worldgen.json` before creating a new server world.

For measured ore counts, chunk details and guarded terrain clearing, see
[Admin tools](ADMIN_TOOLS.md). Surveys read loaded chunks only; clearing and
undo need explicit permission, a preview and a verified backup.

The server console commands `/orespawn status`, `/orespawn reload`, and
`/orespawn dump-biomes` help pack authors diagnose active providers and IDs.
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Choose the guide that matches what you are doing:
- [Configuration field reference](CONFIGURATION.md)
- [Provider JSON files](PROVIDERS.md)
- [Java API and custom patterns](API.md)
- [Natural rock formations](ROCK_FORMATIONS.md)
- [Admin commands, ore surveys and guarded clearing](ADMIN_TOOLS.md)
- [Ore patterns and runtime tools](FEATURES.md)
- [Templates](TEMPLATES.md)
- [Biomes and world materials](BIOMES.md)
Expand Down
58 changes: 58 additions & 0 deletions docs/ROCK_FORMATIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Natural rock formations

Vanilla granite/diorite/andesite patches are country-rock decoration, not
metal ores. `OreSpawnApi.isNativeStonePatchPass()` is a thread-local read-only
pass query so expanded natural-rock blocks can decline that decoration while
remaining ordinary metal-ore hosts. OreSpawn clears it on each ore event,
at the end of the ore pass and at world reset; nested passes restore their outer
context. Height caches hold only weak world references. Old profiles without formations
never activate it. Early placement also accepts plain/natural vanilla stone
variants spilled in from a neighbour, but not polished stone, infested blocks,
ore, structures, fluids or tile entities. This makes the formation substrate
independent of whether that native patch ran before or after its chunk.

Provider schema 6 adds `rock_formations`. Older provider schemas and the ordinary
`rocks` layer catalogue keep their existing behavior. A formation is a natural
substrate body, not an ore promise. Every declaration captures an explicit
`algorithm_revision`, enabled state, priority, deterministic salt, geometry and
resolved output materials. Definitions are copied into a new world's profile.

Existing profiles with no section stay without formations, including later
chunks. An existing unprofiled world also starts without them. There is no
formation retrogen. Explicit pack/world entries win over provider defaults.
`Original Strata` retains Mineralogy's modest defaults rather than applying the
Realistic Deposits tuning. Disabling physical terrain or choosing Cyano suppresses
the formation pass. The exact vanilla Overworld generator supports normal,
Amplified, Large Biomes and Customized worlds, with the same lava-lake
protection in each. Custom generators, including subclasses of the vanilla
generator, fail closed for prediction, placement and native patch protection.

Built-in compilers: `orespawn:alkaline_complex`, `granitic_contact`,
`ultramafic_alteration`, `barren_pipe`, `quartz_vein`, `weathering_profile`.
The built-in algorithm revision is 1. All default rules are Overworld-only.
Bodies stay within their deterministic region; coordinates use floor division,
including negative regions. Weathering evaluates warm, wet climate and the
parent below the profile. It does not turn any clay into a bauxite setting.

`WorldgenProvider.Builder.rockFormation(id, type, definition)` declares a body.
`RockFormationRegistry.register(type, compiler)` registers an immutable compiler
during initialization. Compilation resolves blocks, families and settings once;
the registry freezes on first compilation. A prepared column returns either a
baked `FormationMaterial` or null for unchanged country rock. No world mutation
belongs in a compiler. A compiler must be deterministic and must not obtain
chunks, resolve registries or read configuration while sampling.

The early terrain pass and `GeologyColumn.rockAt`/`familyAt` share that prepared
evaluator. `formationAt(y)` is an additive, read-only query exposing the winning
formation ID, algorithm revision, immediate parent state and material. An empty
family is intentional for vein fill and regolith, not a random layer family.
The query describes planned natural substrate: caves, fluids, structures, ores
and subsequent decorations can leave protected gaps in the realised body.

Placement only exchanges the exact predicted original country rock in the
current chunk, before OreSpawn ores. It preserves tile entities, structure
bounding boxes, caves, fluids and other ores. No compensation fills protected
gaps. Reload requires a restart for formation geometry or policy changes.

This contract is local and unreleased. Add-ons must use checksum-bound local
candidate dependencies until an engine release is separately authorised.
7 changes: 7 additions & 0 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,10 @@ Provider mods suppress native generation only after
- `/orespawn reload` reloads providers and the active world profile.
- `/orespawn retrogen [radius]` queues currently loaded chunks only.
- `/orespawn dump-biomes` writes `config/orespawn-biomes.txt`.
## Checking ore distribution

Use `/orespawn survey 1` in a loaded test area, then `/orespawn jobs <job-id>`
to find the JSON/CSV reports. Compare coverage and height ranges before
comparing ore counts. `/orespawn explain <rule-id> [x y z]` explains current
eligibility without changing settings or rolling a generation attempt.
See [Admin tools](ADMIN_TOOLS.md) for permissions, limitations and safe clearing.
Loading
Loading