NICECHUNK TECHNICAL GUIDE

Understand the world before you trust it

NiceChunk combines a fast local game with rules and state that can be independently checked. These guides explain the current implementation in plain language, separate presentation from authority, and point to the source behind every technical claim.

Choose a learning path · finished pages are published one at a time
The NiceChunk villager boy mines a block while the villager girl scans flowers and cotton beside a forge table, with a supported exact-scale cottage preview visible on the distant hill.
31 Reviewed guides Only source-checked pages appear in the catalog. A listed guide can still be a local release candidate; production publication and its live route are verified separately.
2 Rule boundaries Canonical generated structures and PDA-driven mutable tables have different jobs.
1 Shared forge engine Chunk.js owns the forge codec, editing rules, meshing, tools, and runtime restoration.

SEVEN PLAYER LEARNING PATHS

Start with the question you want answered

The guide is organized around player questions rather than source-code folders. Existing deep technical pages stay available, while focused beginner pages are published one verified topic at a time.

PATH 1 · START HERE

See the whole system before learning its names

Start with the complete system map, learn what four different observations can prove, then follow one visible action in implementation detail.

PATH 2 · PLAYER, WALLET, AND CONTROL

Understand who owns a character and who may act

Start with external-wallet connection and approval safety, compare the browser-held Game Wallet with Seed's exact-message proof and central registration, then follow public identity, temporary authority, separate funding objects, browser policy windows, and Solana chain time without turning a session key into the owner.

2.1 Reviewed 14 min

Wallet Login and Safety: What Connection Allows

Learn what connection shares, how message and transaction approvals differ, what to inspect, and which secrets must never be shared.

Open guide →
2.2 Reviewed 24 min

Local Game Wallet: Backup, Signing, and Recovery

See where the browser keeps its full signing secret, how backup and funding gates differ, what it can sign, and why Disconnect is not deletion or recovery.

Open guide →
2.3 Reviewed 24 min

Seed Whitelist Signatures, Central Registration, and NCK Evidence

Learn what the NiceChunk Seed message signature proves, what the central SQLite service stores, and why a displayed 100 NCK amount is not an on-chain payment.

Open guide →
2.4 Reviewed 28 min

Character Creation: Fixed Models, Three Records, and Local Handoffs

Follow wallet binding, a non-reserving name read, two canonical NCM2 choices, and one owner-signed Player transaction—and learn why confirmation, browser caches, invite registration, and the candidate spawn are separate outcomes.

Open guide →
2.5 Reviewed 27 min

Names, Invite Records, and Candidate Spawn

Learn why a NiceChunk name index, an invited-wallet registration, and a browser-side candidate spawn are three separate outcomes, who signs each action, and what the current Play entry actually uses.

Open guide →
2.6 Reviewed 24 min

PlayerProfile PDAs: Identity, Equipment Identities, and Chain Skills

See how compact Profile identities, separate PlayerEquipment custody, immutable ForgedItem models, Appearance, name claims, Backpack inventory, and authoritative PlayerSkills combine without becoming one all-purpose account.

Open guide →
2.7 Reviewed 27 min

PlayerAppearance: Model Codes, Reconstruction, and Safe Fallbacks

Follow the 9,612-byte public Appearance record through loose chain storage checks, browser source precedence, NCM2 and NCM4 reconstruction, safe fallback, SDK drift, treasury close, and dated Devnet evidence.

Open guide →
2.8 Reviewed 37 min

Equipment and Custody: The Record Moves With the Tool

Follow complete records through Backpack, PlayerEquipment, and Market custody; see how unique ForgedItem PDAs preserve NCF1 geometry and how mining settles forged durability on chain.

Open guide →
2.9 Reviewed 42 min

Displayed Stats vs Enforced Effects: Trace Every Number to a Consumer

Separate stored and displayed values from real consumers in local movement, Chunk mining, Smelting, Backpack Forging, Skills progression, and Guardian boundaries.

Open guide →
2.10 Reviewed 48 min

Skills, XP, and Progress: The Authoritative On-Chain Path

Follow source counters, PlayerSkills, SkillRuleTable thresholds, mining proofs, rule revisions, immediate refresh, and cross-device recovery for all ten skills.

Open guide →
2.11 Reviewed 56 min

One Wallet Approval Can Create an Expiring NiceChunk Pass—but It Does Not Sandbox the Key

Learn how one wallet approval creates an expiring NiceChunk PlayerSession, what its ordinary session key can still sign, which actions consume the pass, and why refresh, funding, logout, expiry, and Guardian do not sandbox or revoke that key.

Open guide →
2.12 Reviewed 54 min

Session Funding and Expiry: A Target Is Not a Balance, and Browser Time Is Not Chain Time

Separate the browser's 0.1 SOL target from owner, session-authority, and PlayerSession-rent balances, then compare browser policy windows with Solana Clock before deciding whether to top up, reuse, refresh, replace, or recover a key.

Open guide →
2.13 Reviewed 62 min

Transaction Fees, Account Rent, and Recovery: Who Pays and What Can Return

Inventory exact transaction fee payers, account-rent payers, close instructions, refunds, stranded balances, and recovery prerequisites without treating every lamport as the same kind of cost.

Open guide →
PATH 3 · WORLD, TERRAIN, AND MINING

Follow a coordinate from base terrain to accepted removal

Learn which world facts are reconstructed, which living surfaces come from PDA rules, and why trees and support collapses use different settlement models.

PATH 4 · BACKPACK, PRODUCTION, AND TRADE

Trace a resource from ownership to processing and exchange

Follow exact Backpack records through Smelting, forging, escrow, payment, delivery, rollback, and the current presentation boundaries.

PATH 5 · CHARACTER MODELS AND BUILDINGS

See how compact bytes become visible characters and structures

Separate model formats, verified bounds, protected foundations, sharded payloads, Guardian discovery, reconstruction, and collision.

PATH 6 · GUARDIAN AND MULTIPLAYER

Keep realtime delivery separate from persistent authority

Inspect how Play discovers a bounded regional relay, what nearby messages it carries, and what still needs Solana evidence.

PATH 7 · TRUST, GOVERNANCE, AND ENGINE

Inspect the roots, rule changes, and renderer budgets

Use the deepest current references to understand root configuration, caller-supplied governance tallies, atomic adapters, and the limits of high-performance reconstruction.

IMPLEMENTATION PRIMER

Read the state model, then inspect the exact code

The equation gives one compact mental model for a rendered block. The snippets below are copied from the current Chunk.js runtime and checked against their source files during every Docs build.

One coordinate, three rendering sources

B_runtime(p) = firstDefined(pending(p), renderDelta(p), G_current(seed, p))

The first available rendering source wins. A reversible local edit keeps interaction immediate, a stored render delta overrides the base, and the deterministic generator reconstructs an untouched coordinate. The runtime's internal chainDeltas name is not independent chain proof: manual local confirmation and Guardian hints can also reach that collection, so shared-state claims still require a validated PDA read.

B_runtime(p)
The block the local Chunk.js scene renders at integer coordinate p.
pending(p)
A local transaction preview that can still be confirmed or rolled back.
renderDelta(p)
The runtime delta currently used for that coordinate. Its collection name does not prove whether it came from a validated RPC snapshot, a manual local confirmation, or a Guardian hint.
G_current(seed,p)
The current canonical terrain, fluid, or generated-tree voxel. generationVersion is carried in configuration but currently selects no alternate algorithm. PDA-driven surface decorations remain a separate face-bound layer.

The first available layer wins

JavaScript chunk.js/chunk/chunk-state.js
  getFinalBlock(localX, localY, localZ) {
    if (!containsLocal(localX, localY, localZ, this)) return BLOCK_ID.air;
    if (!this.pendingDeltas.size && !this.chainDeltas.size) return this.getBaseBlock(localX, localY, localZ);
    const key = deltaKey(localX, localY, localZ, this.chunkSize);
    const pending = this.pendingDeltas.get(key);
    if (pending) return pending.blockId;
    const chain = this.chainDeltas.get(key);
    if (chain) return chain.blockId;
    return this.getBaseBlock(localX, localY, localZ);
  }

Pending edits remain separate and reversible. The internal chainDeltas collection overrides the base, while untouched cells fall through to canonical generation. Because local Confirm and Guardian hints can also populate that render layer, a separate validated RPC snapshot is required before calling it shared chain state.

Canonical inputs become one block answer

JavaScript chunk.js/world/world-generator.js
export function getBlockAt(worldSeed, worldX, worldY, worldZ, ruleVersion = DEFAULT_GENERATION_VERSION, options = {}) {
  const config = createWorldGeneratorConfig({ ...options, worldSeed, generationVersion: ruleVersion });
  const x = Math.trunc(worldX);
  const y = Math.trunc(worldY);
  const z = Math.trunc(worldZ);
  return blockAtConfig(config, x, y, z);
}

The public query normalizes the world position to integer voxel coordinates and passes the selected seed and ruleVersion into configuration; the current generator has no version-dependent branch.

HOW TO READ THESE DOCS

Trust comes from clear boundaries

The project is easier to evaluate when every layer says exactly what it does and what it does not do.

01

Show the authority

Every guide identifies whether a result comes from deterministic code, a PDA rule table, a signed transaction, or local presentation.

02

Keep the game responsive

Selection, animation, previews, and meshing can happen locally without pretending that those visual moments are already shared state.

03

Link claims to code

Evidence paths at the end of each topic make important statements inspectable instead of asking readers to accept marketing language.