📖 About
CosmeticBoxConfig is a R.E.P.O. mod that configures cosmetic box spawns per level within the game's original spawn-volume rules.
✨ Features
- Two modes: Fixed (targets N actual boxes) or Random (at least 1 actual box, then vanilla probability)
- Configurable count: 0–20 boxes in Fixed mode (0 = no boxes)
- Spawn-volume safe: Guarantees are only made within the game's original cosmetic spawn-volume rules when available entries exist
- Fixes level 1 minimum: Random mode ensures at least one actual box when a valid original spawn volume exists
- BepInEx config: Edit
BepInEx/config/cosmetic.box.config.cfg to change settings
- In-game config UI: Mode is an enum selector switchable left/right between Random and Fixed in the game's mod settings UI
- Random-sequence friendly: Patched chance gates still consume the original chance-roll random value to reduce downstream random-sequence offsets
- Multiplayer-safe bypass: The mod only affects the host/master client or singleplayer; when joining someone else's room as a client, it automatically bypasses itself and preserves vanilla behavior
⚙️ How It Works
Fixed mode forces the cosmetic chance gate until BoxCount actual boxes have spawned, then forces later chance checks to fail to avoid extra boxes. It uses a small compensation window (up to BoxCount × 3 - 1 attempts) to retry when an internal spawn attempt fails, while staying within the original spawn volume limits. If another mod or game update rejects spawns internally, the result may fall below the target; with normal vanilla spawn volumes available, the compensation attempts should reach the configured target.
Random mode forces only the first actual box, then returns to the game's native probability. If the level has no available original cosmetic spawn volume, the game will still spawn no box.
🔧 Configuration
After running the mod once, edit:
BepInEx/config/cosmetic.box.config.cfg
[General]
## Spawn mode:
## Random - At least 1 actual cosmetic box when an original spawn volume is available; remaining rolls use vanilla probability.
## Fixed - Targets BoxCount actual cosmetic boxes when original spawn volumes are available, with compensation attempts.
## Changes apply on the next level load, not mid-level.
# Setting type: SpawnMode
# Default: Random
Mode = Random
## Fixed mode cosmetic boxes.
## 0 = 0 cosmetic boxes.
## 1-20 = target actual cosmetic box count, limited by original spawn-volume availability.
## Ignored in Random mode. Changes apply on the next level load.
# Acceptable values: 0-20
# Default: 1
BoxCount = 1
📦 Installation
Thunderstore / Mod Manager
- Install the dependency
BepInEx-BepInExPack-5.4.2305.
- Install this package with Thunderstore Mod Manager / r2modman.
- Launch the game; the DLL is installed as
BepInEx/plugins/CosmeticBoxConfig.dll.
Manual Install
- Install
BepInEx-BepInExPack-5.4.2305.
- Extract this package and make sure the file lands at
BepInEx/plugins/CosmeticBoxConfig.dll under the game folder.
- Launch the game. After the first run,
BepInEx/config/cosmetic.box.config.cfg is generated.
🧩 Compatibility
This mod only patches cosmetic box spawn logic in ValuableDirector.SetupHost. It does not modify EnemyDirector, LevelGenerator, or any other system. Monster counts and other level generation logic are unaffected.
The mod does not create new spawn points and does not bypass the game's original cosmetic spawn-volume / rarity-selection limits. If a level, room, or game version provides no valid vanilla cosmetic spawn volume, Fixed or Random mode can still produce 0 boxes or fewer boxes than the configured target.
In multiplayer, this mod only applies on the host/master client or in singleplayer. Non-host clients joining someone else's room automatically bypass the mod logic and keep vanilla behavior.
问题反馈
