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

    <script type="module" src="./main.js"></script>

Consumer claims start from the current production entry.

1. Line 1

   Load the modular game entry for /play/.

pub const DEFAULT_HEALTH: u16 = 100;
pub const DEFAULT_ENERGY: u16 = 100;
pub const DEFAULT_STAMINA: u16 = 100;
pub const DEFAULT_MINING_POWER: u16 = 1;
pub const DEFAULT_BUILD_POWER: u16 = 1;
pub const DEFAULT_DEFENSE: u16 = 0;

These constants describe Profile initialization, not skill levels.

1. Constants

   Define health, energy, stamina, mining power, build power, and defense.

    const skillState = buildProfileSkillState({
      chainXp: chain.playerSkillXp || chain.skillXp || null,
      chainLevels: chain.playerSkillLevels || chain.skillLevels || null,
      chainThresholds: chain.playerSkillThresholds || chain.skillThresholds || null,
    });

UI passes PlayerSkills XP, levels, and SkillRuleTable thresholds.

1. Inputs

   Select chain values from Player snapshot.

2. Boundary

   No local behavior profile participates.

  function renderOverview(profile, chain, skillState) {
    const [px, , pz] = getPlayerPosition?.() ?? [0, 0, 0];
    const chainBackpack = chain.chainBackpack || {};
    const levels = effectiveSkillLevels(skillState);
    const totalSkillLevels = Object.values(levels).reduce((sum, value) => sum + value, 0);
    const level = Math.max(1, 1 + Math.floor(totalSkillLevels / Math.max(1, PLAYER_SKILL_DEFINITIONS.length)));
    const reputation = Math.max(0,
      Number(profile.confirmedMines || 0) * 5
      + Number(profile.confirmedPlacements || 0) * 3
      + Number(profile.materialsSmelted || 0) * 4,
    );
    const chunkX = Math.floor(px / 16);
    const chunkZ = Math.floor(pz / 16);
    const regionX = Math.floor(chunkX / 100);
    const regionZ = Math.floor(chunkZ / 100);
    const backpackValue = chainBackpack.backpackAddress
      ? `${chainBackpack.syncedSlots || 0} / ${chainBackpack.capacity || 0}`
      : ui("main.profile.noBackpack", "No backpack");
    const balance = chain.walletAddress && Number.isFinite(Number(chain.walletBalanceSol))
      ? `${formatSol(chain.walletBalanceSol)} SOL`
      : ui("main.profile.balanceUnavailable", "0 SOL");

    setText(elements.profileIdentityBalance, balance);
    setText(elements.profileLevelValue, String(level));
    setText(elements.profileReputationValue, reputation.toLocaleString());
    setText(elements.profileRegionValue, `NiceChunk / ${regionX}, ${regionZ}`);
    setText(elements.profileBackpackValue, backpackValue);
    renderStats(skillState);
  }

Overview level is a presentation formula over PlayerSkills levels.

1. Level

   Average ten chain levels for visible Level.

2. Identity

   Render wallet, region, and Backpack separately.

export function createProfileSkillEffects({
  chainXp = null,
  chainLevels = null,
} = {}) {
  const state = buildProfileSkillState({ chainXp, chainLevels });
  const level = (skillId) => {
    const skill = SKILL_BY_ID[skillId];
    return skill ? profileSkillStateLevel(state, skill) : 0;
  };
  const levels = Object.fromEntries(PLAYER_SKILL_DEFINITIONS.map((skill) => [skill.id, level(skill.id)]));
  const effects = Object.fromEntries(PLAYER_SKILL_DEFINITIONS.map((skill) => [
    skill.effect.key,
    profileSkillEffectValue(skill, levels[skill.id]),
  ]));
  return {
    levels,
    ...effects,
  };
}

Runtime does not infer a level from local XP or behavior.

1. State

   Build normalized state from supplied chain values.

2. Effects

   Evaluate each definition at authoritative level.

    let precision_level = player_skill_level(
        player_skills,
        global_config.key,
        &context.owner,
        PRECISION_GATHERING_SKILL_INDEX,
    )?;
    let exploration_level = player_skill_level(
        player_skills,
        global_config.key,
        &context.owner,
        EXPLORATION_SKILL_INDEX,
    )?;
    Ok((
        PlayerProgressState::precision_gathering_volume_mm3_from_level(precision_level),
        exploration_level,
    ))
}

fn player_skill_level(
    player_skills: &AccountInfo,
    global_config: &Pubkey,
    owner: &Pubkey,
    skill_index: usize,
) -> Result<u8, solana_program::program_error::ProgramError> {
    let (expected, _) = Pubkey::find_program_address(
        &[PLAYER_SKILLS_SEED, global_config.as_ref(), owner.as_ref()],
        &NICECHUNK_SKILLS_PROGRAM_ID,
    );
    require_key_eq(
        player_skills.key,
        &expected,
        NicechunkChunkError::InvalidPlayerSkillsPda,
    )?;
    if player_skills.owner == &system_program::ID && player_skills.data_len() == 0 {
        return Ok(0);
    }
    require_key_eq(
        player_skills.owner,
        &NICECHUNK_SKILLS_PROGRAM_ID,
        NicechunkChunkError::InvalidPlayerSkillsOwner,
    )?;
    let data = player_skills.try_borrow_data()?;
    if data.len() != PLAYER_SKILLS_LEN
        || data[0..8] != PLAYER_SKILLS_MAGIC
        || u16::from_le_bytes([data[8], data[9]]) != PLAYER_SKILLS_VERSION
        || data[11] != 1
        || &data[PLAYER_SKILLS_OWNER_OFFSET..PLAYER_SKILLS_OWNER_OFFSET + 32] != owner.as_ref()
        || &data[PLAYER_SKILLS_GLOBAL_CONFIG_OFFSET..PLAYER_SKILLS_GLOBAL_CONFIG_OFFSET + 32]
            != global_config.as_ref()
    {
        return Err(NicechunkChunkError::InvalidPlayerSkillsData.into());
    }
    let level = data
        .get(PLAYER_SKILLS_LEVELS_OFFSET + skill_index)
        .copied()
        .ok_or(NicechunkChunkError::InvalidPlayerSkillsData)?;
    if level > MAX_SKILL_LEVEL {
        return Err(NicechunkChunkError::InvalidPlayerSkillsData.into());
    }
    Ok(level)
}

Chunk derives and validates PlayerSkills before mining effects.

1. Load

   Read two skill indexes.

2. Identity

   Check PDA, owner, layout, wallet, GlobalConfig, and range.

    const resourceId = Number.isFinite(hit.resourceId) ? hit.resourceId : def.resourceId;
    const txId = `local-pending-${txSerial++}`;
    const skillEffects = getSkillEffects?.() ?? {};
    const yieldBps = Math.max(1, Math.min(10000, Math.trunc(skillEffects.precisionGatheringBps || 5000)));
    const volumeMilliLiters = Math.max(1, Math.floor(1000 * yieldBps / 10000));
    const planBlocks = currentPlanBlocks(swing, hit);
    const plannedRewardBlocks = swing.miningPlan?.rewardBlocks?.length ? swing.miningPlan.rewardBlocks : planBlocks;
    const rewardGroups = rewardGroupsForBlocks(uniqueMiningBlocks([hit, ...plannedRewardBlocks]), {
      yieldBps,
      volumeMilliLiters,
    });

Pending reward groups use Precision for responsiveness.

1. Effect

   Read Precision basis points.

2. Preview

   Build local volume and rewards that remain pending.

    let smelting_level = player_skill_level(player_skills, global_config.key, owner.key)?;
    let skill_output_bps = PlayerProgressState::smelting_output_bps_from_level(smelting_level);

    let validated_inputs = {
        let backpack_data = backpack.try_borrow_data()?;
        BackpackAccountView::validate_recipe_inputs(
            &backpack_data,
            owner.key,
            indexes,
            fuel_indexes,
            &recipe,
            multiplier,
        )?
    };

    let recipe_input_volume_mm3 = recipe_input_volume_mm3(&recipe);
    let mut output_volumes_mm3 = [0_u32; state::RECIPE_MAX_OUTPUTS];
    let mut output_quantities = [0_u32; state::RECIPE_MAX_OUTPUTS];
    for output_index in 0..recipe.output_count as usize {
        let output = &recipe.outputs[output_index];
        output_volumes_mm3[output_index] = smelting_recipe_output_volume_mm3(
            &recipe,
            output,
            validated_inputs.input_volume_mm3,
            recipe_input_volume_mm3,
            multiplier,
            skill_output_bps,
        )?;
        output_quantities[output_index] = smelting_output_quantity(
            &recipe,
            output,
            validated_inputs.consumed_input_units,
            multiplier,
            skill_output_bps,
        )?;
    }

The program reads the authoritative PlayerSkills level and validates every resulting output volume and quantity before it consumes any Backpack input.

1. Level

   Decode Smelting level.

2. Output

   Apply the level-derived basis points while precomputing checked output volume and quantity arrays.

    pub fn smelting_output_bps_from_level(level: u8) -> u16 {
        let level = u16::from(level.min(10));
        SMELTING_SKILL_BASE_OUTPUT_BPS
            .saturating_add(level.saturating_mul(SMELTING_SKILL_OUTPUT_BPS_PER_LEVEL))
            .min(SMELTING_SKILL_MAX_OUTPUT_BPS)
    }

Contract formula matches current browser Smelting metric.

1. Clamp

   Limit level to ten.

2. Basis points

   Add 500 per level and cap at 15,000.

    let material_level =
        material_item_level_from_durability(total_effective_durability, total_volume);
    let item_level = material_level.max(1);
    let item_level_grade = 1_u8.saturating_add((item_level.saturating_sub(1) / 10).min(9));
    let blended_grade = ((material_grade as u16 * 3 + item_level_grade as u16 + 2) / 4) as u8;
    let grade = blended_grade
        .max(1)
        .min(10)
        .min(material_grade.saturating_add(1).min(10))
        .min(weak_grade_cap);

    let material_factor = 90_u64.saturating_add(grade as u64 * 5);
    let level_factor = 100_u64.saturating_add(item_level as u64 / 2);
    let base_candidate = total_effective_durability
        .saturating_mul(material_factor)
        .saturating_mul(level_factor)
        / 10_000;
    let base_material_cap = total_raw_durability.saturating_mul(105) / 100;
    let base_durability = base_candidate.max(1).min(base_material_cap.max(1));
    let durability_bonus_percent = 100_u64.saturating_add(forging_level.min(10) as u64 * 5);
    let durability_max = base_durability
        .saturating_mul(durability_bonus_percent)
        .saturating_div(100)
        .max(1)
        .min(u32::MAX as u64) as u32;

    ForgeOutcome {
        grade,
        item_level,
        durability_max,
        quality_bps,
        volume_mm3: total_volume.max(1).min(u32::MAX as u64) as u32,
        mass_grams: 0,
        gained_xp: 1,
    }

Backpack derives grade and base durability from materials, applies exactly five percent per verified Forging level up to level ten, and awards one XP for every completed forge.

1. Grade

   Blend material and item-level grade, then apply material-derived caps.

2. Durability

   Cap the material-derived base, then apply the five-percent-per-level multiplier.

3. XP

   Award one XP for the completed forging action.

export const PLAYER_MOVEMENT_CONFIG = Object.freeze({
  baseSpeed: 14.8,
  sprintMultiplier: 2,
});

export function playerMovementSpeeds(movementSpeedMultiplier = 1) {
  const parsed = Number(movementSpeedMultiplier);
  const skillMultiplier = Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
  const walking = PLAYER_MOVEMENT_CONFIG.baseSpeed * skillMultiplier;
  return {
    walking,
    running: walking * PLAYER_MOVEMENT_CONFIG.sprintMultiplier,
  };
}

export function applyPlayerMovementSpeeds(controls, skillEffects = {}) {
  const speeds = playerMovementSpeeds(skillEffects.movementSpeedMultiplier);
  if (controls) {
    controls.speed = speeds.walking;
    controls.sprintMultiplier = PLAYER_MOVEMENT_CONFIG.sprintMultiplier;
  }
  return speeds;
}

The chain-backed level reaches controls.speed and sprintMultiplier.

1. Config

   Set base 14.8 and sprint 2.

2. Calculation

   Apply skill to walking and derive running.

3. Consumer

   Write values to controls.

  encodeMove({ x, y, z, yaw, pitch }) {
    const chunk = this.worldToChunk(x, z);
    const local = this.globalToLocalChunk(chunk.x, chunk.z);
    const offsetX = x - chunk.x * this.chunkSize;
    const offsetZ = z - chunk.z * this.chunkSize;
    const bytes = new Uint8Array(MOVE_SIZE);
    const view = new DataView(bytes.buffer);
    view.setUint8(0, MSG_MOVE);
    view.setUint8(1, clampByte(local.x));
    view.setUint8(2, clampByte(local.z));
    view.setUint16(3, clampU16(Math.round(offsetX * this.positionPrecision)), true);
    view.setUint16(5, clampU16(Math.round(y * this.positionPrecision)), true);
    view.setUint16(7, clampU16(Math.round(offsetZ * this.positionPrecision)), true);
    view.setUint8(9, encodeYaw(yaw));
    view.setInt8(10, encodePitch(pitch));
    view.setUint16(11, ++this.clientTick & 0xffff, true);
    return bytes;
  }

Realtime movement payload has pose fields but no PlayerSkills or stat table.

1. Position

   Encode chunk-local x, y, and z.

2. Orientation

   Encode yaw and pitch.

3. Ordering

   Include a client tick, not skill state.

export function buildProfileSkillState({
  chainXp = null,
  chainLevels = null,
  chainThresholds = null,
} = {}) {
  const levels = normalizeSkillLevels(chainLevels);
  const xpBySkill = normalizeSkillXp(chainXp);
  const thresholdsBySkill = normalizeSkillThresholds(chainThresholds);
  return {
    levels,
    xpBySkill,
    thresholdsBySkill,
    resolvedLevels: { ...levels },
    source: "chain",
  };
}

Final state normalizes only chain-supplied values.

1. Inputs

   Accept chain XP, levels, and thresholds.

2. Result

   Return one chain-sourced state.