Check the connection or return to the guide index.
Back to guide indexNICECHUNK 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
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.
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.
NiceChunk in One Picture
How the browser, Chunk.js, Guardian, Solana programs, PDAs, models, baked materials, and deterministic reconstruction cooperate without pretending every frame is on chain.
Open guide →Four Truth Layers: What Each Observation Proves
Why a local response, a Guardian hint, a confirmed instruction, and a clean reconstruction are useful evidence without proving the same thing.
Open guide →From Fast Feedback to Verified Action
What happens locally, what is submitted, what the program checks, and when the visible world is allowed to commit.
Open guide →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.
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 →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 →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 →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 →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 →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 →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 →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 →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 →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 →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 →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 →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 →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.
The Deterministic World
How a seed and integer coordinates reconstruct the untouched terrain, while player changes remain separate state.
Open guide →Water: One Level, Many Visible Depths
How deterministic beds fill to one sea-level plane while top-only meshes, packed depth, fragment light, and action rules remain separate.
Open guide →Rule PDAs and Surface Life
Why plants and other one-face objects come from a versioned rule table instead of item-specific contract branches.
Open guide →ResourceDropTable PDAs: Ordered Exploration Extras
How spatial filters, coordinate hashing, Exploration weighting, first-hit order, lossy Backpack writes, and split program scope define current extra drops.
Open guide →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.
Backpack PDAs: Owned Slots and Reconstruction
How owner-derived public accounts, trusted append paths, dense deletion, packed block identity, and Chunk.js previews turn authoritative records into a usable inventory.
Open guide →Cotton, Backpack, Cloth, and Forge
How a deterministic cotton rule becomes a capacity-sensitive reward, a consumed recipe input, and a forge-ready cloth material.
Open guide →Smelting Recipe PDAs: Stack Quantities, Yield Math, and Authority Boundaries
How supplied recipe tables, quantity-bearing Backpack records, heat tiers, atomic conversion, per-output yield math, and current client parity gaps define what a smelting transaction really proves.
Open guide →Material-Aware Forging
How editable 3D work, inherited material properties, immutable NCF1 model accounts, and three on-chain capacity checks fit together.
Open guide →Marketplace Listing PDAs: Escrowed Slots, Split Payments, and Atomic Delivery
How seller-derived listing PDAs remove whole Backpack records, split SOL or NCK payments, deliver through a signed market authority, and expose current discovery and cancellation limits.
Open guide →See how compact bytes become visible characters and structures
Separate model formats, verified bounds, protected foundations, sharded payloads, Guardian discovery, reconstruction, and collision.
NCM Codes: Stored Bytes, Verified Bounds, Rebuilt Geometry
How NCM aliases, avatar cuboids, material-aware building commands, chain validation, and Chunk.js reconstruction remain distinct.
Open guide →Protected Foundations and Verifiable Buildings
How exact-scale NCM3 previews, protected BuildSites, sharded payload checks, Guardian discovery, and Chunk.js reconstruction fit together.
Open guide →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.
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.
GlobalConfig Genesis: Fixed Bytes, NCK Mint, and Enforcement Boundaries
How one 293-byte root PDA, an authority-free NCK mint predicate, legacy world fields, selective downstream reads, binary drift, and upgrade authority define the current genesis trust boundary.
Open guide →Civilization Rule Lifecycle: Centrally Attested Power, Caller-Selected Tallies, and Atomic Adapters
How fixed-authority power accounts, signer PDAs, caller-selected tally inputs, execution receipts, and target-program adapters define the current Civilization trust boundary.
Open guide →Chunk.js: Rebuild Only What Changed
How compact state, dirty rebuilds, Workers, packed meshes, visibility filters, and frame budgets keep the verifiable world responsive.
Open guide →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
JavaScriptchunk.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
JavaScriptchunk.js/world/world-generator.jsexport 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.
Show the authority
Every guide identifies whether a result comes from deterministic code, a PDA rule table, a signed transaction, or local presentation.
Keep the game responsive
Selection, animation, previews, and meshing can happen locally without pretending that those visual moments are already shared state.
Link claims to code
Evidence paths at the end of each topic make important statements inspectable instead of asking readers to accept marketing language.