docs: rewrite the phase 0 comments to explain what the numbers mean by tastybento · Pull Request #548 · BentoBoxWorld/AOneBlock

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento · 2026-08-02T16:55:36Z

Why

An admin asked:

in the phases config, what do the numbers represent, as I couldn't see anything in the wiki about it — as in the numbers after the Material or Entity... I know it is not the number that spawn over the phase, is it a weighting?

They were right, and 0_plains.yml — the file we point admins at as the reference — never said so. Nor did it mention the part that actually bites: blocks:, mobs: and custom-blocks: all draw from one shared pool, so a mob weight is directly comparable to a block weight and adding mobs makes every block rarer.

What

Rewritten comments in 0_plains.yml. The header now separates the three distinct kinds of number a phase file contains, since conflating them is the real source of the confusion:

Weights — blocks:, mobs: and custom-blocks: values. One shared pool, weight ÷ phase total. Not counts, not percentages.
Positions — fixedBlocks: and holograms: keys. Block count within this phase, from 0.
The section name — the top-level '0': key. Historically the start block; phases_index.yml has owned order and length since 1.26.0.

Each section then gets its own explanation:

A worked example on the Winter phase (the one the admin quoted), and the real Plains percentages computed from the actual file — 11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5%, CHEST: 200 is 1.7%, COW: 150 is 1.2%, EMERALD_ORE: 10 is 0.08%.
Why only the ratio matters, and why the shipped files use big numbers.
CHEST as a special case: its weight is the chance of a chest; rarity is a second roll at the hard-coded 62/25/9/4.
That custom-blocks:' probability: field is a weight in the same pool despite the name, plus the mob, itemsadder, nexo and craftengine types that were missing from the list.
Version gating on individual blocks and mobs via the weight: object form.
What actually happens when a mob is rolled (block becomes STONE if empty, mob spawns on top, clear-blocks makes space).

Comments only — verified with git diff that every block, mob and weight is byte-identical, and the parsed YAML is unchanged (blocks total 11450, mobs total 665, same fixedBlocks/holograms/biome/icon/name). OneBlocksManagerTest passes.

Note for existing servers

Phase files are only copied out of the jar when the phases folder is first created, so existing installs keep their old 0_plains.yml and will not see these comments. The companion docs PR covers those admins: BentoBoxWorld/docs#85 adds a "Customizing Phases" page and corrects the AOneBlock overview, which described weights only as "relative probability" and never mentioned the shared pool.

0_plains.yml is the reference file admins read first, but it never said what the numbers after a Material or EntityType are. An admin asked, and they were right to guess weighting: they are relative weights in a single raffle - not counts and not percentages - and blocks, mobs and custom-blocks all draw from that same pool, so a mob weight is directly comparable to a block weight and pushes every block's share down. The header now separates the three distinct kinds of number a phase file contains, since that is the real source of the confusion: 1. blocks/mobs/custom-blocks values are weights, one shared pool 2. fixedBlocks and holograms keys are positions within the phase, from 0 3. the top-level key is the section name - phases_index.yml has owned phase order and length since 1.26.0 Each section then gets its own explanation with the real Plains numbers worked out (11450 block weights + 665 mob weights = 12115, so GRASS_BLOCK: 2000 is 16.5% and COW: 150 is 1.2%), plus the CHEST two-stage roll, the mob/custom-block types that were missing from the list, and version gating. Comments only - every block, mob and weight is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017zwLryefnJ6wG76JmYNamx

sonarqubecloud · 2026-08-02T16:57:16Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tastybento merged commit 1b7c097 into developAug 2, 2026
1 check passed

tastybento deleted the docs/phase-file-instructions branch August 2, 2026 16:57

tastybento mentioned this pull request Aug 8, 2026
Release 1.27.0 #552
Merged