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.110021.jar
build/libs/OreSpawn-4.1.6.110021-sources.jar
build/libs/OreSpawn-4.1.6.110021-javadoc.jar
build/libs/OreSpawn-4.1.7.110021.jar
build/libs/OreSpawn-4.1.7.110021-sources.jar
build/libs/OreSpawn-4.1.7.110021-javadoc.jar
build/release/SHA256SUMS
CHANGELOG.txt

Expand Down
29 changes: 29 additions & 0 deletions CHANGELOG.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,32 @@
Version 4.1.7.110021

* Keep completed retrogen marked through later saves and restarts, even while
retrogen is off. Do not mark chunks with a revision they have not processed.

* Add loaded-chunk ore surveys, JSON/CSV reports, chunk details and rule
explanations. Keep read-only diagnostics independent of generation settings.
* Restore terrain clearing with permission checks, a preview, a verified
backup and checked undo. Keep ores, fluid deposits and unknown blocks safe.
Show short previews with clickable confirmation, cancellation and undo links.

* Keep saved ore settings when a provider renames a recognised rule. Add the
matching modern rule as a disabled alternative rather than another ore pass.

* Add provider/profile declarations and compiled natural rock formations.
Use the same deterministic, chunk-local geometry for early terrain placement
and geology prediction, with read-only formation and parent-material queries.
* Preserve caves, fluids, structures, other ores and existing chunks. Existing
worlds without formation definitions keep that absence in later terrain too.
* Let realism templates tune untouched packaged formations while preserving
authored, disabled, removed and authoritative external definitions.
* Keep native granite/diorite/andesite patches from cutting the expanded
formation rocks differently according to chunk population order, without
changing normal metal-ore hosts or older profiles.
* Preserve natural formation rock in vanilla lava-lake rims regardless of
neighbouring chunk order. Keep native lake shapes, fluid cavities and random
draws unchanged in normal, Amplified, Large Biomes and Customized worlds;
leave older profiles and custom generators alone.

Version 4.1.6.110021

* Fix duplicate ore generation when an OreSpawn 1 world is moved without its
Expand Down
21 changes: 18 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,17 @@ 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.110021`: the OreSpawn 4.1.6
This branch builds local candidate `4.1.7.110021`: the OreSpawn 4.1.7
feature set for Minecraft 1.10.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 and
a biome directory with exact new-terrain replacement overrides, plus a client
world-settings extension point for add-ons such as Realistic Deposits
while retaining API major 1. See the
world-settings extension point for add-ons such as Realistic Deposits.
Natural rock formations now share their compiled geometry between early
terrain placement and read-only geology prediction, including formation and
parent-material provenance. Missing formation sections in saved worlds remain
empty; this is not retrogen or a wholesale 4.2 backport. API major 1 is retained.
See the
[versioning policy](docs/VERSIONS.md) for the encoding and release convention.

Its deprecated compatibility layer imports OreSpawn 1 and OreSpawn 3
Expand All @@ -27,6 +31,10 @@ metadata block states, exclusive legacy height ceilings, and the historical
Metals. OreSpawn never schedules both an original legacy generator and its OS4
translation.

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 @@ -208,3 +216,10 @@ Public developer and AI integration guidance lives in `docs/` and is included
in the built jar.

OreSpawn is licensed under LGPL-2.1.

## Admin and distribution tools

Use `/orespawn help` for loaded-chunk surveys, rule explanations and chunk
diagnostics. Guarded `/orespawn clearchunk` previews one chunk before changing
it and keeps a verified backup for checked undo. Open chat to review the preview
and choose Confirm clearing or Cancel. See [the admin guide](docs/ADMIN_TOOLS.md).
7 changes: 5 additions & 2 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,9 @@ tasks.withType(JavaCompile).configureEach {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
options.encoding = 'UTF-8'
// javac 8 can emit different anonymous-class constant pools after a partial
// incremental compile. Compile the complete source set for stable jar bytes.
options.incremental = false
options.compilerArgs.addAll(['-Xmaxerrs', '1000'])
}

Expand Down Expand Up @@ -189,8 +192,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
131 changes: 131 additions & 0 deletions docs/ADMIN_TOOLS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# 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
snapshot requires a new preview. 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 1 And OreSpawn 3 Compatibility On Minecraft 1.10.2

This branch ships deprecated compatibility bridges for existing OreSpawn 1 and
Expand Down
4 changes: 4 additions & 0 deletions docs/PLAYER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,5 +180,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 @@ -14,6 +14,8 @@ API and provider references for the details.
- [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
Loading
Loading