Summary
总结

v1.3.1

This hotfix fixed the missing bot angle-spread setting.

• It now appears in the settings menu.
• It is now correctly mapped to the trigger system for non-OP players.

Players using v1.3.0 with command permission can still access this setting directly with:

/function app:settings/pool/bot/angle_std

Alternatively, please update to v1.3.1.

v1.3.0

This update introduces the first playable Minecraft pool bot across all supported versions, including the recent Minecraft 26.2, together with substantial cross-version performance improvements and an optional whitelist-based permission system for shared servers.
Minecraft 1.21 and later additionally receive configurable ball radius, dynamic table scaling, item-display-based table rendering, and related table-size controls.

---

Main features

1. Configurable ball radius and dynamic table scaling

Minecraft 1.21 and later only

• Added support for changing the pool-ball radius in Minecraft 1.21 and later.

  • The default radius remains 1250.
  • Table dimensions, including table length, width, pocket size, and related placement offsets, can now be calculated dynamically from the selected ball radius.
  • Pocket-center and pocket-edge positions are now configured dynamically.
  • Increased the physics engine detection limit to support smaller ball radii.

• Redesigned the Minecraft 1.21+ table-rendering system to support dynamic scaling.

  • Replaced table-related item frames with item displays.
  • Item displays allow table components to be positioned and scaled according to the selected ball radius.
  • Cloth rendering now uses a solid cloth color where appropriate to avoid texture-stretching artifacts.

• Added an optional perfectly scaled 1×2 table mode.

  • This allows the playable area to retain an exact 1:2 width-to-length ratio for players who prefer accurate table proportions.
  • Enable this option in the settings menu and select any 1×2 table-size combination, such as 4×8 or 6×12, for it to take effect.

• Added a fixed table-scale option.

  • By default, pockets and other table components scale with the selected ball radius when a new table is placed.
  • equipment/table_scale_fix keeps the pockets and related table components at the dimensions used for the default ball radius.
  • equipment/table_scale_unfix restores radius-dependent scaling.
  • This recovers the previous ability to change only the ball size without changing the table and fake-ball dimensions.
  • It can also be used to slightly reduce the game difficulty by decreasing the ball radius while keeping the table dimensions unchanged.

---

2. Pool Bot

a. Supported games

• Added full bot support for:

  • 8-ball, the primary and highest-priority supported bot game.
  • 9-ball, which has a smaller legal action space and is generally simpler for the bot to evaluate.

• Added a start-with-bot option to single-player games.

  • This turns a single-player session into a two-player game between the player and the bot.

• Added supporting bot behavior for:

  • Game-specific rules and legal-target handling.
  • Cue-stick movement animation when the bot shoots.
  • Ball-in-hand situations.
  • Snooker get-out situations.
  • Muting normal game sounds during internal simulations.

• Replaced area-effect-cloud helper entities with markers in Minecraft 1.17 and later where applicable.

  • This improves the visual appearance of bot actions and related helper behavior.

b. Bot difficulty and performance settings

• Added configurable bot difficulty and performance settings.

• Added control over the number of aim points evaluated by the bot.

  • Higher values allow the bot to evaluate more candidate shots.
  • Evaluating more aim points generally makes the bot stronger, but also increases its thinking time.
  • Because the benefit decreases as more lower-ranked shots are added, and the most difficult shot is unlikely to be the best choice, the default value is 2.

• Added configurable random shot-angle spread.

  • Lower values produce more accurate shot execution and therefore a stronger bot.
  • Higher values introduce more aiming error.
  • Adjust this setting according to your preferred difficulty.

• Added two force-spin action spaces:

  • action_space_5: evaluates 5 force-spin combinations per aim point.
  • action_space_10: evaluates 10 force-spin combinations per aim point and generally makes the bot stronger.

• Added configurable tick time allocated to each bot simulation.

  • Increasing this value gives the game more time to recover between simulations.
  • This helps prevent lag from accumulating and reduces the catch-up acceleration that may otherwise occur after intensive simulations.
  • Recommended values are based on the 5-combination action space and may need to be doubled when using the 10-combination action space.
  • The configured tick time is also used to calculate the total delay between scheduled bot simulations.

c. Bot decision logic

- Candidate action generation

• The bot currently prioritizes direct potting attempts.

  • The design assumption is that sufficiently accurate direct shots can handle most normal situations.
  • Bank shots, combination shots, swerve shots, and dedicated safety-shot actions are not currently included in the primary action space.
  • However, the bot may occasionally identify one of these shots as favorable during simulation and choose to play it.

• Candidate actions are generated from legal target-ball and pocket pairs.

• Actions with cut angles greater than 90 degrees are rejected.

• Actions with obviously blocked cue-ball paths are removed before computationally expensive simulation.

  • The bot precomputes the relative distance D and angle A between each object ball and the cue ball.

  • The offset between the aiming direction and the direction toward another object ball is used for obstruction checks.

  • A target path may be treated as blocked when:

    D × sin(A) < 2 × ball radius

    and the obstructing ball is closer than the selected aim point.

  • A squared-vector form is used to avoid unnecessary square-root calculations.

• If the path from a legal target ball to the selected pocket is blocked, the action is penalized rather than completely removed.

  • These actions remain valid because collisions or combination shots may still produce a favorable result.

- Initial shot-quality estimate

• Each candidate action receives an initial score S, representing the approximate probability of potting the target ball.

• S is estimated using fitted linear relationships based on:

  • Cue-ball-to-target-ball distance.
  • Target-ball-to-pocket distance.
  • Cut angle.
  • The incoming-path angle relative to the direction faced by the pocket.

• These relationships were derived from 200,000 offline simulations.

• Candidate actions are ranked using this initial estimate before full simulations are performed.

- Simulation and action evaluation

• The number of evaluated aim points and force-spin combinations determines the approximate bot thinking time.

• The bot simulates a selected number of highly ranked actions and evaluates the resulting table state.

• Each simulated action is also evaluated using the estimated quality of the best available action on the bot’s next turn.

• The general evaluation structure is:

  FS = S × (R + S_next_best)

  where:

  • FS is the final evaluation score for the current action.
  • S is the estimated quality of the current shot.
    • When R ≠ 1, S is set to 1 so that non-potting outcomes are evaluated directly from the shot result and resulting table state.
  • R represents the result of the current shot:
    • 1: a successful pot.
    • 0: no successful pot.
    • -1: a foul.
    • 2: a win.
    • -2: a loss.
  • S_next_best is the estimated quality of the best available action on the bot’s next turn.

• The evaluation also:

  • Penalizes resulting positions with too few available actions, reducing the chance of the bot getting stuck.
  • Rewards positions that preserve possible shots on multiple object balls.

• The bot selects the action and force-spin combination with the highest final evaluation score.

- Fallback behavior

• If no normal candidate actions are available because all paths are blocked or no pocket path can be found:
  • The bot attempts a randomly selected target ball.
  • It additionally tests shots in 12 distributed directions.

- Ball-in-hand and break-shot behavior

• During ball-in-hand:

  • The bot tests random legal cue-ball placements.
  • It favors placements that produce a high value for the best currently available shot.
  • Normal action evaluation is then performed from the selected position.

• During a break shot:

  • The bot places the cue ball at a random legal location.
  • The bot then attempts to hit the first ball fully with high power.

- Silent rollout system

• Added an efficient silent-simulation pipeline that evaluates candidate shots and returns their results.

• During each simulation, the system:

  1. Records the current ball positions and game state.
  2. Creates static ball displays to preserve the visible table state.
  3. Hides the actual physics-enabled balls and mutes all related sound effects.
  4. Simulates the candidate shot using the hidden actual balls until all balls stop moving.
  5. Evaluates and records the shot result according to the applicable game rules.
  6. Restores the original ball positions and game state.
  7. Removes the temporary static ball displays.
  8. Reveals the actual balls and restores normal sound effects.

---

3. Server permissions and settings access

• Added an optional whitelist restriction for table management and protected settings.

  • As requested in issue #23, restricted features include table configuration and placement, as well as global settings.
  • Player-specific settings and normal game controls, such as starting or stopping a game, remain unrestricted.

• The whitelist restriction can only be enabled or disabled by an OP.

  • The enable and disable controls remain direct function commands rather than trigger-based commands.
  • Players without command permission cannot activate them.

• When whitelist restriction is enabled:

  • The OP enabling the restriction is automatically added to the whitelist.
  • OPs retain full administrative control.
  • OPs can add or remove the swPool_whitelisted tag from players.
  • Whitelisted players can access protected settings and table-management functions.
  • Whitelisted non-OP players cannot enable or disable the whitelist or modify whitelist membership.
  • Other non-OP players cannot access protected settings or table-management functions.
  • In the settings menu, restricted entries are displayed in gray to players who do not have permission.
  • Restricted scoreboard triggers used by settings are enabled only for whitelisted players.

• When whitelist restriction is disabled:

  • All players can access settings and table-management functions as before.

• Access restrictions are enforced within the trigger system itself, so restricted settings cannot be bypassed by manually entering their trigger values.

• In single-player worlds without command permission:

  • The whitelist cannot be enabled.
  • The player can continue to use all normal trigger-accessible features.
  • This preserves normal single-player usability because whitelist restrictions are not useful in this situation.

---

4. Performance improvements

• Substantially improved datapack performance, making repeated bot simulations practical across all supported versions.
  • Reduced repeated entity-selector usage by moving more operations into helper functions.
  • Reduced unnecessary square-root calculations.
  • Reduced unnecessary precision in spin calculations for a significant performance improvement.

---

5. Fixes and gameplay refinements

• Fixed a rule-logic bug affecting replacement of colored balls in snooker.

• Optimized rack placement locations for all supported games.

• Added cushion restitution behavior.

---

6. Scope decisions

• Bot simulation is currently built and tuned around the default ball radius of 1250.

  • Support for variable ball radii is not included yet, but will likely be added in a future version.

• Full snooker bot gameplay is not included.

  • Snooker requires substantially more complex rule handling, stronger decision-making algorithms, and significantly more com✨g power.

• Bank shots, combination shots, swerve shots, and dedicated safety-shot actions are not explicitly included in the current normal action-selection system.

  • They are lower priorities because direct shots cover the main intended gameplay.
  • However, the bot may still occasionally discover and select some of these shots during simulation.

---

7. Upgrade and gameplay notes

• It is recommended to completely remove existing tables after updating to v1.3.0 and then place them again.

  • This ensures that each table uses the updated entity types, scaling logic, pocket placement, and rendering system.

• Automatic judging must be enabled when playing with the bot.

• Some settings can become inconsistent if they are changed after a table has already been placed.

  • For example, changing the ball radius without replacing the table may create mismatched ball and table dimensions.
  • Normal behavior is not guaranteed in these cases.

• Avoid setting friction values too low when playing with the bot.

  • Lower friction causes simulated shots to take much longer to finish, which substantially increases bot simulation and thinking time.

• Avoid using the bot on multiplayer servers or during time-sensitive single-player gameplay, such as combat or other hazardous survival situations.

  • Bot simulations are very unlikely to finish within a single game tick under normal hardware conditions.
  • The required computation can cause noticeable lag and may negatively affect other players or make time-sensitive situations unsafe.