Update the bundled guides and KubeJS nexus readings for 0.5.6

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.6.121012 beta
+
+I’ve brought the guides in the JAR up to date with player pools, timed transfers, nexus pins, and the smaller nexus reserves. The Java quick start now shows how to get Ley Lines from MMD Maven, and the KubeJS guides cover player pools and job events.
+
+- KubeJS `LeyLines.inspectAt` now gives you the nexus centre. If the nexus is a named pin, you also get its ID and authored height, so a pack can recognise a site even when the player is some distance from its anchor.
+- The JAR manifest now reports save schema 6, which 0.5.5 already used for nexus capacity changes. Worlds keep their saved layout, accounts, and player pools.
+
 ## 0.5.5.121012 beta
 
 I wanted magic mods to be able to share a nexus even when they use completely different kinds of magic. A technomancer can now carry aether and a mage can carry mana. Each mod decides who gets a pool and how big it is, and both can draw from the same nexus.

README.md

@@ -18,6 +18,6 @@ The [documentation index](docs/README.md) is also in the mod JAR at `META-INF/sk
 
 ## Install
 
-This beta is for **Minecraft 1.21.1, NeoForge 21.1.247 or later in the 21.1 line, and Java 21**. Use the same build on the server and clients. See the [changelog](CHANGELOG.md) for what’s changed since the alpha.
+The **0.5.6.121012 beta** is for **Minecraft 1.21.1, NeoForge 21.1.247 or later in the 21.1 line, and Java 21**. Use the same build on the server and clients. The [release guide](docs/RELEASE-0.5.6.md) covers upgrading and the optional KubeJS stack. See the [changelog](CHANGELOG.md) for earlier changes.
 
 If you’re working on the source, use the [Eclipse setup guide](ECLIPSE.md). The Windows development launcher uses a [guarded GLFW runtime](GLFW.md).

build.gradle

@@ -112,7 +112,7 @@ tasks.named('processResources', ProcessResources) {
 tasks.named('jar', Jar) {
     manifest.attributes('Specification-Title': "Sky's Ley Lines", 'Specification-Version': '2',
             'Implementation-Version': project.version, 'SkysLeyLines-API-Version': '2',
-            'SkysLeyLines-Layout-Version': '1', 'SkysLeyLines-Save-Schema': '5',
+            'SkysLeyLines-Layout-Version': '1', 'SkysLeyLines-Save-Schema': '6',
             'SkysLeyLines-Documentation': documentationIndex)
 }
 tasks.named('javadoc', Javadoc) {

docs/API.md

@@ -49,7 +49,7 @@ var returned = power.returnToRawAt(x, y, z, AETHER, 1000, plant);
 // Success removes 1000 aether and restores exactly 1 raw at the saved rate.
 ```
 
-Every paradigm, player, and machine shares one account per nexus. Consumers may use currencies they understand from any paradigm. Raw magic is a conversion reserve, not a directly spendable currency. There are no per-player wallets or per-currency capacities.
+Every paradigm, player, and machine draws from the same account at a nexus. Consumers may use currencies they understand from any paradigm. Raw magic can fund conversion into registered currencies. All nexus balances count toward one capacity. A child mod can also open [personal pools](PLAYER_ENERGY.md) that hold converted units outside the nexus, with a separate capacity for each player and currency.
 
 `raw + sum(currency units / unitsPerRaw)` is the total charge. Conversion and return preserve this total; spending reduces it. A capacity reduction can leave retained energy above the new limit. Such accounts can still convert, spend, and return energy. They cannot recharge or accept deposits until there is room. Recovery adds raw into the remaining space at `capacity / rechargeTicks` per Overworld game tick. It works while chunks are unloaded, without wall-clock/offline recovery or a per-node tick loop. Elapsed recovery is settled before a transaction, preventing retroactive recovery into space that spending just freed.
 

docs/CONFIGURATION.md

@@ -53,7 +53,7 @@ Admin pins use a restart-applied overlay. See [Worldgen and nexus pins](WORLDGEN
 
 ## Player energy policy
 
-Player pools and timed operations have their own JSON policy layers. See [Player energy pools](PLAYER_ENERGY.md) for data pack and server files, death behavior, and the schema 4 upgrade.
+Player pools and timed operations have their own JSON policy layers. See [Player energy pools](PLAYER_ENERGY.md) for data pack and server files, death behavior, and save compatibility.
 
 ## Shared accounts and recharge
 

docs/INTEGRATION.md

@@ -2,21 +2,28 @@
 
 Compile against the ordinary Sky’s Ley Lines JAR for NeoForge 1.21.1. Install that mod separately in the runtime. If your integration is optional, declare it as optional in `META-INF/neoforge.mods.toml` and use a dedicated integration class. Check `ModList.get().isLoaded("skysleylines")` before loading that class so your mod can start when the dependency is absent.
 
-For a local Gradle build, a direct compile dependency can look like this.
+Use the ordinary artifact from MMD Maven. This example pins the version documented here.
 
 ```groovy
+repositories {
+    maven {
+        url = 'https://maven.moddev.zone/releases/'
+        content { includeGroup 'zone.moddev.mc.skysleylines' }
+    }
+}
+
 dependencies {
-    compileOnly files('libs/SkysLeyLines-0.5.4.121012.jar')
+    compileOnly 'zone.moddev.mc.skysleylines:SkysLeyLines:0.5.6.121012'
 }
 ```
 
-Stage the ordinary dependency JAR as a mod in your development run’s `mods` directory. For release, declare a version range that covers the API you use and the versions you tested. This example declares an optional dependency on the exact build documented here. Replace `yourmod` with your mod ID and use `type="required"` if your mod relies on Ley Lines to function.
+For a candidate awaiting publication, you can temporarily compile against the exact local JAR using `compileOnly files('libs/SkysLeyLines-0.5.6.121012.jar')`. Stage the ordinary dependency JAR as a mod in your development run’s `mods` directory. For release, declare a version range that covers the API you use and the versions you tested. Replace `yourmod` with your mod ID and use `type="required"` if your mod relies on Ley Lines to function.
 
 ```toml
 [[dependencies.yourmod]]
 modId="skysleylines"
 type="optional"
-versionRange="[0.5.4.121012]"
+versionRange="[0.5.6.121012]"
 ordering="AFTER"
 side="BOTH"
 ```
@@ -26,9 +33,11 @@ Choose an entry point based on the job.
 | Job | Entry point | When to call it |
 | --- | --- | --- |
 | Read natural strength for ores, structures, or rituals | `LeyLinesApi.forLevel(level).field()` and `LeyFieldSampler.sampleColumn(x, z)` | Acquire the sampler on the server thread during level load. Its retained sampler supports worker reads. |
+| Find nexus sites in a structure callback | `LeyLinesApi.worldgenSampler(randomState)` and `LeyFieldSampler.nexusesInChunk(chunkX, chunkZ)` | Query on the generation worker. See the [worldgen guide](WORLDGEN_AND_PINS.md). |
 | Register a paradigm and currencies | `LeyLinesApi.paradigms().register(...)` | Common setup via `enqueueWork`, before registration freezes at load complete. |
 | Inspect balances or pay for a machine action | `NexusPowerService.quoteAt`, `convertAt`, `spendAt`, or `returnToRawAt` | On the owning server thread. Use the position where the action happens. |
 | Read saved rates and active flags | `LeyLinesApi.currencyInfo(level)` | On the server thread. |
+| Give players personal pools or move energy over time | `LeyLinesApi.playerPower(server)` | On the server thread. See [player energy](PLAYER_ENERGY.md). |
 | Show Ley Vision to a player | `LeyVision.grant` or `revoke` | On the connected player’s server thread. Register custom styles during mod setup. |
 | Enforce protection rules or observe a completed transaction | `NexusTransactionEvent.Pre` or `.Post` | Listen on `NeoForge.EVENT_BUS`. Include the player UUID in the request when one is responsible. |
 

docs/MODPACKS.md

@@ -1,12 +1,12 @@
 # Pack maker guide
 
-For NeoForge 1.21.1, ship `config/skysleylines-common.toml` for new-world layout, capacity, and base recharge. Ship `config/skysleylines-server.toml` for the default vision style and optional recharge override. A server operator can place a copy in `<world>/serverconfig/` to set those two values for one world. The Ley Meter and `/skysleylines profile` show the applied settings. See [configuration and save compatibility](CONFIGURATION.md).
+For NeoForge 1.21.1, ship `config/skysleylines-common.toml` for new-world layout, base capacity, and base recharge. Ship `config/skysleylines-server.toml` for the default vision style, recharge override, and nexus capacity multiplier. An operator can place a copy in `<world>/serverconfig/` to tune one world. Reopen the world to apply capacity and recharge changes. The Ley Meter shows the effective capacity and refill time for the nexus you inspect. Use `/skysleylines profile` to check the world settings. See [configuration and save compatibility](CONFIGURATION.md).
 
 From 0.5.5 you can configure player pools and react to balance and job events. See the [player energy guide](PLAYER_ENERGY.md) for examples and policy files.
 
 ## KubeJS
 
-The optional scripting bridge was introduced in Sky’s Ley Lines 0.5.1. Install the matching [KubeJS build 381](https://www.curseforge.com/minecraft/mc-mods/kubejs/files/9396059/additional-files) stack for Minecraft 1.21.1. Put these scripts on the server, or in the instance for single-player packs.
+The optional scripting bridge uses the NeoForge 1.21.1 stack. See [the release guide](RELEASE-0.5.6.md) for tested KubeJS and Rhino builds. Put these scripts on the server, or in the instance for single-player packs.
 
 Save this as `kubejs/startup_scripts/ley_currency.js` and restart the game or dedicated server.
 
@@ -55,7 +55,11 @@ ItemEvents.rightClicked('minecraft:spyglass', event => {
 
 Startup registration takes a unique `kubejs:` currency ID and a positive exact rate string. For a transaction, use a namespaced consumer ID and pass the responsible player when there is one. The script owns gameplay permissions and should apply rewards only after payment succeeds. Omit the vision style to use the server default. See the [public API reference](API.md#convert-spend-and-return) for transaction result codes.
 
-Inspection returns a map with `active`, the field strengths, coordinates, and a nullable `account`. The account has `nexus`, `strength`, `rechargeTicks`, and `balance`. A balance has `raw`, `total`, `capacity`, `tick`, and a `currencies` map keyed by ID. Each currency row has `units`, `unitsPerRaw`, and `active`. Transactions return `succeeded` and `status`. Success adds `nexus`, `revision`, `before`, and `after`. Use map `get` calls to read fields. Balances, ticks and revisions that can exceed JavaScript integer precision are strings. Supply amounts as strings, for example `"1000"` or `"3/2"` for raw magic or rates.
+Inspection is read-only. The result has the sample’s `dimension`, `x`, `y`, `z`, and `active` flag, plus `naturalStrength`, `lineStrength`, `nexusStrength`, `verticalFactor`, and `dimensionalResistance`. An active field can have no eligible nexus, in which case `account` is null.
+
+The account has `nexus` (its stable ID), `strength` (its intrinsic strength), `rechargeTicks` (effective full refill time), and `balance`. Since 0.5.6 it also gives the nexus centre as `x` and `z`. If the account belongs to an active [authored pin](WORLDGEN_AND_PINS.md), it includes `pinId` and `authoredY`. For a seeded nexus those keys are absent, so `account.get('pinId')` returns null.
+
+A balance has `raw`, `total`, `capacity` (after applying the world’s multiplier), `tick`, and a `currencies` map keyed by ID. Each currency row has `units`, `unitsPerRaw`, and `active`. Transactions return `succeeded` and `status`. Success adds `nexus`, `revision`, `before`, and `after`. Use map `get` calls to read fields. Balances, ticks and revisions that can exceed JavaScript integer precision are strings. Supply amounts as strings, for example `"1000"` or `"3/2"` for raw magic or rates.
 
 Use `/reload` for server script changes. Restart the entire process for startup definitions. A world keeps its saved rates when a pack changes a definition. Use the [rate migration commands](CONFIGURATION.md) to apply changed rates. Removing a definition or the KubeJS mod marks the retained currency inactive until the same ID returns.
 

docs/PLAYER_ENERGY.md

@@ -77,7 +77,7 @@ The order is child code, data pack, instance file, then world file. A layer only
 
 Default death policy is `DROP`. Active balances are emptied and leave collectible energy where the player died. Walk near the floating shards with a compatible pool to collect them. They move only as much as fits, and leftovers stay until collected or expired. By default any eligible player can pick them up, their lifetime is 6,000 server ticks, and `keepInventory` keeps the player’s balance. Other choices are `KEEP` and `LOSE`. `ownerOnly` restricts a drop to its owner. Dormant balances remain in the wallet in every mode.
 
-On the first persistent pool change, the mod backs up the current nexus ledger and upgrades `<world>/data/skysleylines.dat` to schema 4. Player balances and drops live in that same file. Dropped entities are views of the saved balances and reappear when their chunks are loaded. Clients and servers must use matching builds. Back up the world before upgrading. Older builds cannot read schema 4.
+Player balances and drops live in `<world>/data/skysleylines.dat`. Adding player data to an older ledger requires at least schema 4 and a backup before the upgrade. A ledger already using a newer schema keeps it. Dropped entities are views of the saved balances and reappear when their chunks are loaded. Back up the world before upgrading and use matching builds on the client and server. See [save compatibility](CONFIGURATION.md).
 
 ## KubeJS
 
@@ -89,16 +89,16 @@ const surveyPower = 'kubejs:survey_progression'
 
 PlayerEvents.loggedIn(event => {
   const player = event.player
-  const pools = LeyLines.inspectPlayer(player).pools
-  if (!pools[surveyAether]) {
+  const pools = LeyLines.inspectPlayer(player).get('pools')
+  if (pools.get(surveyAether) === null) {
     LeyLines.configurePool(player, surveyAether, true, '1000', '3/2', surveyPower)
   }
 })
 
 ItemEvents.rightClicked('minecraft:spyglass', event => {
-  if (event.hand !== 'MAIN_HAND') return
+  if (event.hand.name() !== 'MAIN_HAND') return
   const paid = LeyLines.spendPool(event.player, surveyAether, '10', surveyPower)
-  if (paid.succeeded) LeyLines.grantVision(event.player, surveyPower, 1200, 'skysleylines:crackle')
+  if (paid.get('succeeded')) LeyLines.grantVision(event.player, surveyPower, 1200, 'skysleylines:crackle')
 })
 
 LeyLinesEvents.playerPoolEmpty(event => {
@@ -110,5 +110,5 @@ Use `inspectPlayer(player)` or `inspectPlayer(server, uuid)`, `configurePool(pla
 
 For transfers use `withdrawToPlayer(player, currency, units, schedule, source)`, `depositFromPlayer(player, currency, units, schedule, source)`, and `transferPlayers(from, to, currency, units, schedule, source)`. For raw conversion use `scheduleConversion(level, x, y, z, currency, raw, schedule, source[, actor])`. Pass `'instant'`, `'duration:40'`, or `'rate:3/2'` for the schedule. Timed submissions return `status: 'RUNNING'` and a `jobId`. Read progress with `energyJob(server, jobId)` or cancel with `cancelEnergyJob(server, jobId)`. Balances, rates, and completed amounts are returned as exact strings.
 
-`LeyLinesEvents.playerPoolChanged` provides `playerId`, `currency`, `before`, `after`, `receipt`, and `server`. `playerPoolEmpty` has the same fields and fires only when positive units become zero. `energyJobFinished` provides `job` and `server`. These are committed notifications. Use a later server tick to initiate a new transaction from an event.
+`LeyLinesEvents.playerPoolChanged` provides `playerId`, `currency`, `before`, `after`, `receipt`, and `server`. `playerPoolEmpty` has the same fields and fires only when positive units become zero. `energyJobFinished` provides `job` and `server`. Read event properties directly, then use map access for their contents, such as `event.after.get('units')` or `event.job.get('status')`. These are committed notifications. Use a later server tick to initiate a new transaction from an event.
 

docs/README.md

@@ -8,13 +8,13 @@ Start with the guide for what you want to do.
 | --- | --- |
 | Find a ley line or nexus and understand the readings | [Player guide](PLAYER_GUIDE.md) |
 | Install the mod, run operator commands, or check a nexus account | [Server operator guide](SERVER_GUIDE.md) |
-| Change layout defaults, recharge, or Ley Vision style | [Configuration and save compatibility](CONFIGURATION.md) |
+| Change layout defaults, nexus capacity, recharge, or Ley Vision style | [Configuration and save compatibility](CONFIGURATION.md) |
 | Register pack currencies or write KubeJS scripts | [Pack maker guide](MODPACKS.md) |
 | Build a Java mod that samples the field or uses nexus power | [Java integration quick start](INTEGRATION.md) and [public API reference](API.md) |
 | Place structures at nexuses, sample ore candidates, or stage an admin pin | [Worldgen and nexus pins](WORLDGEN_AND_PINS.md) |
 | Set up personal pools, timed transfers, death drops, or KubeJS events | [Player energy pools](PLAYER_ENERGY.md) |
 | Diagnose a missing reading, payment failure, or startup problem | [Troubleshooting](TROUBLESHOOTING.md) |
-| Check version requirements and what changed | [Current release and supported languages](RELEASE-0.5.4.md), [0.5.3](RELEASE-0.5.3.md), [0.5.2](RELEASE-0.5.2.md), and [0.5.1](RELEASE-0.5.1.md) |
+| Check version requirements and what changed | [Current release](RELEASE-0.5.6.md), [0.5.4 and supported languages](RELEASE-0.5.4.md), [0.5.3](RELEASE-0.5.3.md), [0.5.2](RELEASE-0.5.2.md), and [0.5.1](RELEASE-0.5.1.md) |
 
 ## Finding this guide in a JAR
 

docs/RELEASE-0.5.6.md

@@ -0,0 +1,17 @@
+# Sky’s Ley Lines 0.5.6.121012 beta
+
+I’ve updated the guides that ship inside the JAR so pack makers and modders can find the player energy, worldgen, and nexus pin features in one place. KubeJS can now identify a named nexus from an account reading, including its authored height. The JAR manifest reports schema 6, the save format already supported in 0.5.5.
+
+## Install or upgrade
+
+- Use Minecraft 1.21.1, NeoForge 21.1.247 or later in the 21.1 line, and Java 21. Install the same Ley Lines build on the server and clients.
+- The optional KubeJS stack uses [KubeJS NeoForge 2101.7.2-build.381](https://www.curseforge.com/minecraft/mc-mods/kubejs/files/9396059) and [Rhino 2101.2.7-build.85](https://modrinth.com/mod/rhino/version/cQ4POTah). See the [pack maker guide](MODPACKS.md) for startup registration and server scripts.
+- Back up your world before upgrading. The seeded layout is version 1, the Java API is version 2, and the network protocol is version 4. This beta reads the same world ledger schemas as 0.5.5. See [configuration and save compatibility](CONFIGURATION.md) before reopening a world from an older beta.
+
+## If you’re coming from 0.5.4
+
+- Mods can give each player personal pools of converted currency and move energy [instantly or over time](PLAYER_ENERGY.md). Pack makers can configure pools and jobs with KubeJS, including what happens to player energy on death.
+- Structure mods can [query nexuses in a chunk](WORLDGEN_AND_PINS.md) during world generation. Operators can stage named nexuses and retire or recover old pins.
+- Nexus capacity defaults to 1% of its base value. Use the [server capacity multiplier](CONFIGURATION.md) to change it and reopen the world.
+
+See the [documentation index](README.md) and the [list of supported languages](RELEASE-0.5.4.md).