DummyPool

DummyPool

A high-performance billiards plugin for Paper servers, developed with AI‑assisted coding.

Offers 5 table types, a realistic physics engine, and complete rule sets for Chinese 8‑Ball, 9‑Ball, and Snooker. All 34 physical parameters are saved independently per table, and all messages, particles, and sounds are fully customizable.

✨ Features

• 🎱 5 Table Types: Chinese 8‑Ball, 9‑Ball, Snooker, Carom, and Round
• ⚙️ Independent Physics: 34 parameters (friction, elasticity, spin decay, etc.) saved per table
• 🎨 Fully Customizable: Chat messages (message.yml), particles & sounds (config.yml) editable by server owners
• 🧠 AI‑Assisted: Stable, well‑structured logic with optimized performance

📐 1. Table Types & Dimensions

Type	Key	Table Size (Blocks)	Pockets	Description
🇨🇳 Chinese 8‑Ball	cn8	3 × 5 (Half‑W 1.5, Half‑L 2.5)	6	Solids (Concrete 1–7) + Stripes (Wool 9–15) + Black 8
🔵 9‑Ball	9-ball / nine_ball	3 × 5 (Half‑W 1.5, Half‑L 2.5)	6	Diamond rack 1–9; first contact must hit the lowest‑numbered ball
🎩 Snooker	snooker	4 × 7 (Half‑W 2.0, Half‑L 3.5)	6	15 Reds + 6 Colors; D‑shaped baulk area
🟡 Carom	carom	3 × 5	None	Pocketless table; scoring via cannons
⭕ Round Table	round	Radius = [size] blocks	None	Circular table; particle outline forms a circle

📌 Creation Note: Stand at the target position facing the long side of the table. Snooker tables use special 4×7 alignment (long edge center on block, short edge on block border).

Sneak trigger: A non-creator standing one block outside the foot end of the table (height difference 0–2 blocks) while holding a cue in the off-hand and sneaking will open the ball library if they have the required permission. If the table is unowned, the first player to trigger this will be claimed as the creator and the management menu will open.

🛠️ 2. Creation & Management Commands

2.1 Create a Table

/dummypool create <name> <type> [size]

• Type (required, case‑insensitive): cn8 / 9-ball / snooker / carom / round
• Size: Only required for round – radius in blocks; ignored by other types

2.2 List & Remove

/dummypool list            # Lists all tables
/dummypool remove <name>   # Removes a table (creator only)

2.3 On Success

The default ball set for the selected type is automatically generated, and the table outline is drawn with particle effects.

📋 3. Management Menu (Dialog)

Creators can open the powerful management panel via:

/dummypool ui <table> main
# Shortcut
/dummypool set <table>

The menu features 8 core function buttons:

Button	Description
⚙️ Parameters	Opens the list of 34 physics parameters (3 pages). Click an item to edit; out‑of‑range values are auto‑clamped
🔐 Permissions	4 toggles (🟢 Allow / 🔴 Deny): Open Rack, Place/Take Balls, Hit Balls, Game Mode
📂 Open Rack	Opens the table's ball rack as a vanilla chest interface
🎱 One‑Click Rack	Automatically racks balls per current rules (prompts if balls are missing)
✏️ Rack Edit	Opens a 54‑slot editor: removing a ball strips its table tag; placing it back re‑applies the tag
⚔️ Game Mode	Opens the match Dialog (CN8 / 9‑Ball / Snooker)
📥 Collect Balls	Sends all balls on the table back to the rack (overflow drops to the sensing area)
❌ Close	Closes the management menu

🦵 Sneak Trigger Zone

Non‑creators standing one block outside the table's foot end (height diff 0–2) with a cue in the off‑hand and sneaking will:

• If they have Rack Access → open the rack
• If the table is unowned → the first trigger automatically becomes the creator and opens the menu

Flame particle rings appear under the feet (configurable via sneak_zone in config.yml).

🔑 4. Permission Settings (4 Toggles)

Permission	✅ When Allowed	❌ When Denied
Open Rack	Non‑creators can open the rack	Non‑creators cannot open via sneak or commands
Place/Take Balls	Can place, pick up, and rack balls	Placing and racking are blocked
Hit Balls	Can aim and shoot	Cannot enter the power‑charging state
Game Mode	Can open game menu and join matches	Menu shows no permission

🗄️ 5. Ball Library System

• Opening: Via menu, /dummypool ball lib <table>, or sneaking in the sensing area
• Interaction: Same as vanilla chest. Upon closing, non‑ball items and balls from other tables are returned to the player's inventory
• Edit Rules: Balls taken from the edit interface lose their table tag (and lore). Balls without a tag or with a pending tag get tagged automatically when returned. Balls from other tables are rejected
• Collect Command: /dummypool clear <table> or the menu button collects all table balls (disabled during game mode)
• Full Library: Maximum 54 slots. When full, pocketed balls drop to the ground in the foot‑end sensing area and can be picked up

🎱 6. One‑Click Rack

Command

/dummypool ball place <table> [mode]

• Chinese 8‑Ball / Snooker: no mode needed
• Carom: requires a mode parameter (e.g., /dummypool ball place <table> <mode>)

Process

• Pre‑clear: Automatically collects all table balls before racking (drops if library is full)
• Missing Balls: Chat lists missing balls with [Click Confirm] / [Click Cancel] interactive buttons
• Break Shot: After racking, the next shot on the cue ball counts as the break (speed ×1.3 with break effects)

Default Ball Sets per Table

Table Type	Ball Set
Chinese 8‑Ball	Cue + Solids 1–7 + Black 8 + Stripes 9–15; triangular rack, corner balls from different groups
9‑Ball	Cue + 1–9; diamond rack – 1 at the apex, 9 in the center, others random
Snooker	Cue + 15 Reds + Yellow/Green/Brown/Blue/Pink/Black; placed at standard snooker spots
Carom	Cue + Yellow/Red/Blue

⚙️ 7. Physical Parameters (34 Items, Independent per Table)

Keys match the identifiers in config.yml and the menu. All are adjustable via the management menu.

Parameter (Key)	Default	Effect ↑ (Higher)	Effect ↓ (Lower)
tableFriction	0.11	Balls slow faster, spin wears more	Balls slide farther
slipThreshold	0.01	Enters rolling earlier, travels further	Sliding friction lasts longer, decelerates faster
rollingDeceleration	0.3	Rolling stops quickly	Rolls longer
stopThreshold	0.02	Balls stop early	Balls linger longer
spinDecayX	0.999	Forward/back spin lasts longer	Forward/back spin disappears faster
spinDecayY	0.985	Side spin lasts longer	Side spin disappears quickly
spinDecayScale	1.0	All spins decay faster	All spins decay slower
spinFrictionCouplingX	0.55	Friction neutralizes forward/back spin faster	Draw/follow lasts longer
maxSpinSpeed	150	Allows more spin	Spin effects are limited
collisionDistance	0.30	May trigger early detection	Clamped back to 0.30 by the solver
collisionIterations	15	More stable for touching/fast balls but heavier on performance	May cause tunneling
collisionRestitution	0.93	Bouncier collisions	Softer collisions
collisionSpinTransfer	0.4	Target ball is more likely to be spun	Less effect from english
ballHitFriction	0.3	More cue ball deflection	Almost no deflection
cushionRestitution	0.83	Bounces hard	Absorbs energy (softer)
cushionFriction	0.6	Banana shot is more visible	No deflection on cushion
masseMinAngle	45	Harder to masse	Masse possible at smaller angles
masseMaxAngle	80	Continues strengthening at larger angles	Curve caps earlier
masseCurveCoeff	6.0	Sharper curve	Gentler curve
masseAxisTiltMax	60	Stronger side‑curve	Weaker curve (less tilt)
masseDecayOmegaRef	30	Curve straightens early (short arc)	Curve lasts longer (long arc)
masseBankMax	15	Exaggerated tilt	Mild tilt
masseBankOmegaRef	30	Needs high spin to bank	Banks at low spin
masseOffsetBoost	3.0	Easier to spin and curve	Weaker masse english
jumpAngleThreshold	75	Harder to jump	Easier to jump
jumpMinPowerLevel	4	Needs more power to jump	Can jump with a light hit
jumpVelocityScale	0.5	Jumps higher and farther	Jumps lower
jumpMaxHeight	1.0	Can jump higher	Limited jump height
landingSpinLoss	0.6	Spin is almost gone after landing	Spin remains after landing
collisionSpinTransferX	0.12	Follow/draw spin transfer is more visible	Only slight spin loss during collision
cushionSpinTransferX	0.05	Strong suck‑in / follow effect	Relies only on table friction
cushionSpinLossX	0.25	Forward/back spin drops more on cushion	Retains more spin
cushionSpinLossY	0.3	Side spin vanishes quickly on cushion	Still deflects on multiple rails
cushionTangentialLoss	0.1	Sliding along cushion decays fast	Slides farther along cushion

📖 8. Full Command List

Command	Description	Permission
/dummypool create <name> <type> [size]	Creates a table	Everyone
/dummypool remove <name>	Removes a table	Creator
/dummypool list	Lists all tables	Everyone
/dummypool clear <table>	Collects table balls into library (blocked in game mode)	Place permission
/dummypool ui <table> <action>	Management Dialog (main/params/param/perms/lib/place/edit/game/invite/close)	Creator
/dummypool set <table>	Same as ui main	Creator
/dummypool game <table> enable	Enables game mode	Creator
/dummypool game <table> menu	Opens game Dialog	Game permission
/dummypool game <table> invite <player>	Invites a player	Member
/dummypool game <table> join	Joins the game	Everyone
/dummypool game <table> reject	Rejects invite (5‑minute cooldown)	Everyone
/dummypool game <table> start	Starts the game	Member
/dummypool game <table> end	Ends current session (mode stays)	Member
/dummypool game <table> concede	Concedes in snooker when behind	Member
/dummypool game <table> choice own/let	Snooker foul choice	Non‑offender
/dummypool ball get <type>	Gives a ball (e.g., concrete‑white, glass‑yellow)	OP
/dummypool ball lib <table>	Opens the ball library	Library permission
/dummypool ball place <table> [mode]	Racks balls; confirm/cancel for missing balls	Place permission
/dummypool cue get <name>	Claims a cue	Everyone
/dummypool reloadmessages	Reloads message.yml	OP
/dummypool reloadconfig	Reloads config.yml	OP

---

🚀 DummyPool aims to deliver the most realistic and customizable billiards experience for Minecraft servers. Feel free to submit issues for feedback or bug reports!