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.1.114041.jar
build/libs/OreSpawn-4.1.1.114041-sources.jar
build/libs/OreSpawn-4.1.1.114041-javadoc.jar
build/libs/OreSpawn-4.1.7.114041.jar
build/libs/OreSpawn-4.1.7.114041-sources.jar
build/libs/OreSpawn-4.1.7.114041-javadoc.jar
build/release/SHA256SUMS
CHANGELOG.txt

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

* Add chunk surveys, rule explanations and guarded clear/undo tools with clickable previews.
* Keep completed retrogen revisions through repeated saves, OFF/ON changes and server restarts.
* Add optional natural rock formations and preserve edited provider templates.
* Keep native aquatic decoration working with custom background fluids; preserve later lakes and springs.
* Keep saved ore settings without enabling duplicate provider defaults.
* Refresh release checksums when their jars change and keep Eclipse launches production-only.

Version 4.1.6.114041

* 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.

* Show vanilla ores in Ore Sources before world creation, even when Manage
Vanilla Ores is off.
* Keep vanilla ore placement unchanged with management off. With it on,
imported rules replace their matching defaults without a second pass.
* Keep saved Ore Sources choices and use a shared placement channel for new
built-in patterns. Explicit channels still stay separate.
* Keep imported provider rules and back up affected profiles before removing
untouched duplicates. Keep edited rules and flag them for review.
* Choose sulfur and lithium defaults after mods finish loading, including
Base Electric. Existing worlds keep their choices.
* Fix the Austrian German language ID and add Pirate Speak menu and guide text.

Version 4.1.1.114041

* Fixed a crash when opening or editing OreSpawn's settings in development runs.
Expand Down
15 changes: 14 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,23 @@ Its OS3 compatibility layer preserves ranged legacy block budgets, exclusive
legacy height ceilings, and the historical "all dimensions except Nether and
End" policy used by mods such as Base Metals.

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.

This branch builds target-qualified version `4.1.1.114041` for Minecraft 1.14.4
This branch builds target-qualified version `4.1.7.114041` for Minecraft 1.14.4
and Forge. It adds material-group ore arbitration, exact biome replacements,
and a directory for installed provider mods to the OreSpawn 4.0.16 base. See the
[versioning policy](docs/VERSIONS.md) for the encoding and release convention.

The 4.1.7 update adds [admin and distribution tools](docs/ADMIN_TOOLS.md),
optional provider-defined [natural rock formations](docs/ROCK_FORMATIONS.md),
and fixes for saved ore rules and completed retrogen work. Existing worlds keep
their saved choices; new formations do not appear just because the mod is updated.

I've fixed a crash when opening or editing OreSpawn's settings in development
runs. The fix has also been checked in a normal Forge installation.

Expand Down Expand Up @@ -144,3 +153,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

The [admin guide](docs/ADMIN_TOOLS.md) covers loaded-chunk surveys and guarded clear/undo. The [formation guide](docs/ROCK_FORMATIONS.md) explains optional natural rock formations. Existing worlds keep their saved choices.
19 changes: 16 additions & 3 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ plugins {

group = project.mod_group
version = project.mod_version
base.archivesName = 'OreSpawn'
base.archivesName = project.mod_artifact

def versionParts = project.mod_version.toString().tokenize('.')
if (versionParts.size() != 4 || !versionParts.every { it ==~ /\d+/ }) {
Expand All @@ -36,8 +36,8 @@ if (versionParts[3] != expectedTargetVersion) {
ext.functional_version = versionParts[0..2].join('.')
ext.display_version = project.mod_version
ext.release_tag = project.mod_version
def expectedMavenGroup = 'zone.moddev.mc.orespawn'
def expectedMavenArtifact = 'OreSpawn'
def expectedMavenGroup = project.mod_group
def expectedMavenArtifact = project.mod_artifact
def expectedMavenCoordinate = "${expectedMavenGroup}:${expectedMavenArtifact}:${project.version}"

java {
Expand Down Expand Up @@ -264,13 +264,23 @@ tasks.named('processResources', ProcessResources) {
dependsOn prepareBundledDocumentation
filteringCharset = 'UTF-8'
inputs.property('version', project.version)
['mod_id', 'mod_name', 'mod_license', 'mod_issue_url', 'mod_url', 'mod_authors', 'mod_description'].each { key ->
inputs.property(key, project.property(key))
}
inputs.property('minecraft_version', project.minecraft_version)
inputs.property('forge_version_range', project.forge_version_range)
inputs.property('loader_version_range', project.loader_version_range)
inputs.property('minecraft_version_range', project.minecraft_version_range)
filesMatching('META-INF/mods.toml') {
expand([
version: project.version,
mod_id: project.mod_id,
mod_name: project.mod_name,
mod_license: project.mod_license,
mod_issue_url: project.mod_issue_url,
mod_url: project.mod_url,
mod_authors: project.mod_authors,
mod_description: project.mod_description,
minecraft_version: project.minecraft_version,
forge_version_range: project.forge_version_range,
loader_version_range: project.loader_version_range,
Expand Down Expand Up @@ -316,3 +326,6 @@ apply from: 'gradle/verification/packaged-forge.gradle'
apply from: 'gradle/verification/ore-sources.gradle'
apply from: 'gradle/verification/native-ores.gradle'
apply from: 'gradle/verification/performance.gradle'

apply from: 'gradle/verification/admin-tools.gradle'
apply from: 'gradle/verification/parity.gradle'
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:diorite
/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[property=value]>`. 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 block-tag 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 journal remains available for checked recovery instead of claiming completion.
Only unfinished height and lighting cleanup is retained with the chunk. It resumes
in bounded steps when its lighting area is loaded; block edits never resume by themselves.

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.
10 changes: 9 additions & 1 deletion docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ coverage with `OreDefinition.Builder.dimensionSelector(...)` and
`OreDimensionSelector.ALL_EXCEPT_NETHER_AND_END`. Explicit dimensions
override that selector and prevent duplicate placement.

The builder emits provider schema 5. Legacy provider schemas 1-4 remain
The builder emits provider schema 5, or schema 6 when it declares rock formations. Legacy provider schemas 1-4 remain
readable. Schema 4 is required for biome palettes and dimension materials;
schema 5 adds explicit material and placement-channel IDs. API major remains 1.

Expand Down Expand Up @@ -166,3 +166,11 @@ runs during generation.

`OreSpawnOreIntegration` remains as a deprecated facade for early ore-provider
integrations. New code should use `OreSpawnApi`.

## Formation and background controls

New integrations can use `mergeNewEntriesIntoExistingWorlds(false)` on the
provider builder and `backgroundGenerationScale(value)` on an ore dimension.
Both preserve existing behavior when omitted. Formation declarations and the
read-only `GeologyColumn.formationAt(y)` query are described in
[Natural formations](ROCK_FORMATIONS.md).
9 changes: 9 additions & 0 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ OreSpawn uses three JSON contracts:
| `config/<modid>-orespawn.json` | 5 | Optional authoritative provider override |

A provider may package schema 5 at `data/<modid>/orespawn/provider.json`.
Providers that declare `rock_formations` use schema 6; all existing schemas
remain supported. Formation materials use flattened block IDs and optional
exact `properties`, not numeric metadata.
Legacy provider schemas 1-4 remain accepted. Fluid deposits require schema 3;
biome palettes and dimension materials require schema 4. Explicit ore material
and placement-channel IDs require schema 5.
Expand Down Expand Up @@ -185,6 +188,9 @@ Each enabled ore dimension uses:
| `placement_channel` | registry ID | Independent placement budget shared by equivalent ores in consolidated modes |

At least one of `host_families`, `host_blocks`, or `host_tags` must be present.
On 1.14.4, plain stone, granite, diorite, and andesite are separate block
IDs. Use `host_blocks: ["minecraft:stone"]` for plain stone only; no
pre-flattening metadata is needed.
Hosts may be plain registry IDs or weighted objects such as
`{"tag":"forge:stone","weight":0.75}`. Optional
`geomes`, biome include/exclude IDs, and biome-dictionary include/exclude arrays
Expand Down Expand Up @@ -264,3 +270,6 @@ ordinary solid blocks, and hostless rules are rejected before generation.
Copying a world's `serverconfig/orespawn-worldgen.json` to the same location in
a dedicated server world reproduces its choices when the same referenced mods,
blocks, biomes, dimensions, and tags are installed.
See [Natural formations](ROCK_FORMATIONS.md) for substrate bodies and
[Admin tools](ADMIN_TOOLS.md) for measured distribution reports. Neither
changes existing terrain merely by installing this update.
Loading
Loading