BS Coins · v1.0.0 Release Documentation

1. Short Description (Summary)

English

Turns the "like / coin / favorite" trio into a coin you can actually throw: tip your friends, stun mobs, stick coins into walls, call in airdrops, and dig 3×3 with an over-engineered pickaxe. 73 config options, optional Patchouli guide, MIT licensed.

Tagline (One-liner subtitle)

A throwable coin that tips players, stuns mobs, and sticks to surfaces.

2. Full Description

What is This?

BS Coins is a fan-made "fun + utility" toolkit for NeoForge 1.21.1. The core concept is simple: it turns the Bilibili-style "Like / Coin / Favorite" trio into a physical, throwable coin — complete with physics, tactile feedback, and sound effects.

It is not just a toy box of random items. Projectiles feature full ballistic trajectories, tumbling animations, particle trails, and realistic surface-sticking mechanics. Every item is independent and can be toggled off individually via config. All numerical values are exposed, allowing you to tune them for serious combat or pure entertainment.

Target Audience:

• Multiplayer servers looking for fun social interactions and "tipping" mechanics.
• Technical players wanting a reliable 3×3 mining pickaxe or a damage-testing dummy.
• Content creators seeking unique visual props and gadgets for videos.

Three Components → One BS Coin

Craft these three in any arrangement to create a BS Coin (stacks to 64), unlocking the "Triple Support" achievement. Combine a BS Coin with a Nether Star to create a Dev Edition BS Coin (infinite range, fireproof, Sneak + Q to reload datapacks).

What Can the BS Coin Do?

Throwing Mechanics

This mod pays meticulous attention to throwing feel — this isn't just a flat texture flying through the air.

• Audio & Tumbling: A distinct "whoosh" on release. The coin tumbles along its flight axis with a unique starting rotation per entity (based on UUID), avoiding the "billboard" effect.
• Trails: Leaves a trail of electric sparks based on velocity (Dev Edition uses white glows), making trajectories easy to track.
• Physics: Initial speed 9 blocks/tick, air drag 0.97, gravity 0.055 blocks/tick². Flat throws travel approx. 65 blocks in 0.4 seconds, with terminal descent around 1.8 blocks/tick. High-angle throws (5°–45°) no longer float like feathers. Burns up after exceeding 130 blocks altitude (1-2s burn time).
• Velocity-Based Damage: ~12 damage point-blank, ~11 at 20 blocks, ~10 at 60 blocks (hard cap at 48 as safety valve).
• Impact Feedback: Impact sound + sparks + knockback along the velocity vector (faster hits push further).
• Surface Sticking: Sticks to blocks like arrows without bouncing. Each stuck coin has a unique pose (tilt ±18°, roll ±22°, yaw ±28°, depth 0–0.035). Ground vs. wall impacts use different base angles; ceiling sticks flip upside down. Pose data persists in saves.
• Retrieval: After settling for 0.5s, walking within 1.5 blocks auto-collects the coin (with sound effect; never swallowed). Embedded coins emit a faint glow every 2 seconds for visibility in grass.
• Cooldown: 0.4 seconds. Uses vanilla item cooldown overlay. Configurable to 0 for rapid fire.

Tuning: All feel parameters are configurable: throwSpeed, throwDrag, throwGravity, throwBurnDistance, throwPickupRadius, throwCooldownTicks, throwTrail. To restore the "floaty legacy feel", set physics to 10 / 0.94 / 0.04.

Item Catalog

BS Corner Store: Installing this mod replaces Wandering Trader trades with the catalog above — effectively creating the "BS Corner Store."

Structure Airdrops

Throwing a Structure Airdrop triggers:

1. A real chest model (vanilla texture, 1x1 size) spawns at 40 blocks altitude alongside a flare.
2. Descends at a constant 0.15 blocks/tick (~3 blocks/sec, ~13s total fall time), slowly rotating and swaying with cloud particles. Fall state is saved in NBT; resumes falling after server restart/chunk reload.
3. Lands as a loot chest (facing the thrower) and announces coordinates in chat. If landing spot is occupied, searches vertically for valid ground. If placement fails entirely, loot spawns as dropped items — loot is never lost.
4. Loot = 1 roll from vanilla dungeon table + "Rare Pool": ~22% chance per chest to contain a BS Coins series item (BS Coin most common; Dev Edition ~0.4%).

Debug Tools

• Sneak + Q Test Arena: Instantly places a 20×20 platform underfoot + a test dummy in front. Costs only 1 coin.
• Test Dummy: 100 HP, despawns after 60s by default. Features a Boss Bar countdown. Displays floating damage numbers on hit (actual damage dealt; crits in red; spiral offset prevents overlapping).

BS Coins Guidebook

Optional dependency: [Patchouli]. Craft with Book + BS Coin. Contains 5 categories / 13 entries, bilingual (CN/EN), values synced with game config. Fully playable without it — guidebook datapack assets are lazy-loaded and will not error or spam logs if missing.

Installation

1. Install NeoForge 21.1.248+ for Minecraft 1.21.1 (Client/Server).
2. Place bscoins-1.0.0.jar into mods/.
3. (Optional) Add Patchouli to enable the guidebook recipe.

Compatibility & Known Limitations

• Required on BOTH Client and Server (not server-side only).
• "Replace Wandering Trader" may conflict with other trader-modifying mods → Disable via enableShop = false.
• Dev Assistant GUI, Test Platform/Dummy are debug features; disable on production servers as needed (enableDevAssistant / enableTestPlatform / enableTestDummy).
• Guidebook text is static; manually edit assets/bscoins/patchouli_books/guide/*/entries/*.json if syncing config changes to book text.
• "Right-click Mob Stun/Infight" relies on vanilla Item#interactLivingEntity. Does NOT work on vanilla mobs that consume right-click (tamed wolves/cats, rideable horses, villagers, etc.). Works normally on standard hostiles (Zombies, Skeletons, Creepers).

FAQ

Q: Is client-side installation required? A: Yes. This mod adds keybinds, entity rendering, and client-side particles. Both sides must install it.

Q: Will it crash without Patchouli? A: No. The guidebook is an optional dependency; related datapack files load lazily.

Q: How to configure on a server? A: Edit config/bscoins-common.toml directly. Changes apply on save. NeoForge's built-in file watcher triggers ModConfigEvent.Reloading automatically; no restart needed. (Note: Toggle switches like enableLike affect recipes, which are datapack-level; those require a datapack reload or restart to remove recipes.)

Q: Can I include this in modpacks? A: Absolutely. MIT licensed; inclusion welcome.

Q: Can I disable specific features? A: Yes. Most of the 73 options are toggles/values covering all major components, the coin itself, throwing mechanics, zones, shop, airdrops, and punishment items.

License & Credits

• Released under MIT License (full text in LICENSE.txt, Copyright © QZyme): Free to use, modify, redistribute, and commercialize, provided copyright and license notices are retained. Modpack inclusion and forks welcome.
• Project scaffold based on NeoForge MDK template (MIT, Copyright © 2023 NeoForged project).
• Uses Mojang official mappings (parameter names provided by Parchment).
• Optional guidebook support by Patchouli (not bundled).
• Author: QZyme. Not affiliated with Mojang/Microsoft.

3. Version Metadata