How to Use the Ball Sort Solver
The Ball Sort Solver rebuilds a standard tube puzzle from JSON, checks the exact four-ball rules, searches in the browser, validates every returned move, and lets you replay the answer one exposed ball at a time.
Quick answer
One array value is one ball, and one move transfers one ball
Write each tube from bottom to top, include at least one empty tube as [], make every color appear exactly four times, and verify the tube preview before selecting Solve.
Do not use this solver for liquid layers that pour as a connected group. Check the Water Sort vs Ball Sort guide when the visual theme is unclear.
What the Ball Sort Solver Actually Supports
| Feature | Current behavior | Limit |
|---|---|---|
| Tube input | Bottom-to-top arrays, with supported wrapper objects | Maximum 32 tubes; capacity fixed at 4 |
| Color values | Finite numbers or trimmed non-empty strings up to 32 characters | Every color must appear exactly 4 times |
| Space | Partly filled tubes provide slots during moves | Initial validation still requires at least one explicit empty tube |
| Move rule | Moves one exposed top ball to an empty or same-color target | Adjacent matching balls never move as one group |
| Search | Cancellable, batched heuristic search in the browser | Default limit is 120,000 states or 12 seconds |
| Replay | Previous, Next, Play/Pause, Reset, and a detailed move list | No shortest-solution guarantee |
| Share | Carries the Ball type, tubes, capacity, palette, and checked moves | Only capacity-4 Ball links are restored |
Use a Complete Standard Tube Layout
This is the tested three-color example published in the Ball Sort Solver. Each of the three colors appears four times and the level includes two empty tubes.
[
[1, 2, 3, 1],
[2, 3, 1, 2],
[3, 1, 2, 3],
[],
[]
]The final value in A is 1, so the top ball in Tube A is color 1.
Ball Sort Solver Workflow
Record every tube
Read tubes left to right. Inside each tube, start with the bottom ball and end with the exposed top ball.
Load and preview
Select Load JSON, then compare every circular ball, tube label, and top color with the game.
Pass strict checks
Fix capacity, color-count, empty-tube, or value errors. Solve remains unavailable until the standard level is valid.
Search or cancel
Select Solve. The status reports visited and queued states, and Cancel Search stops the current run without changing the input.
Replay and share
Use Previous, Next, Play/Pause, and Reset. Copy the text result or create a Ball-specific link with validated moves.
Ball Sort Validation Is Stricter Than Water Sort Validation
Required for search
A standard valid level
- Contains at least one tube and at least one color.
- Uses no more than 32 tubes.
- Places no more than 4 balls in any tube.
- Uses exactly 4 balls for every color.
- Includes at least one explicit empty tube
[]. - Uses only finite numbers or short non-empty strings.
Not supported
Variants outside the model
- Hidden or unknown balls.
- Uneven tube capacities.
- Capacity other than 4.
- Automatic helper tubes.
- A rule that lifts several matching balls at once.
- A screenshot sent directly to the solver.
Accepted wrapper shapes
The simplest input is a top-level array. The parser can also find tube arrays under tubes, bottles, level, or data. An individual tube may be an array or an object with a balls or colors array.
How the One-Ball Move Rule Works
The source must have an exposed ball. The target must have an open slot and must be empty or show the same color on top. Even when two matching balls touch, only the final array value moves.
source = [2, 1, 1]
target = [1]source = [2, 1]
target = [1, 1]The remaining top 1 needs a second action. The core rejects any Ball Sort move whose amount is not exactly 1.
Understand the Search Status
Solution found
The returned move list is replayed from the initial level and checked to finish in a solved state.
Already solved
Every non-empty tube is full and uniform, so no moves are needed.
Search limit reached
The current run reached 120,000 visited states or about 12 seconds before finding a solution.
Search cancelled
You stopped the batched search. The loaded JSON and preview remain available.
No solution found
The reachable space under the implemented search was exhausted without a solved state.
Solver error
An unexpected search failure occurred. Recheck input and reload before trying again.
These states are different. A search-limit result is not the same as a proven unsolvable level, and a valid found route is not a promise that no shorter route exists.
Common Ball Sort Solver Problems
| Message or symptom | Likely cause | Correction |
|---|---|---|
| Expected 4, found 3 | A ball was missed or a similar shade was split | Recount that color across every tube |
| Missing empty tube | The outer array has no [] | Add every empty tube shown in the level |
| Top ball is wrong | The tube was recorded top to bottom | Reverse that inner array so the last value is on top |
| Move seems to skip a ball | Input does not match the visible stack | Compare the replay preview with the game tube by tube |
| Search limit reached | The state space was not resolved within current limits | Verify JSON and rules; do not treat it as a shortest-path result |
| Liquid game gives odd steps | The wrong solver was selected | Use the Water Sort Solver for connected liquid pours |
Try the Ball Sort Workflow
Start with the published example, confirm the one-ball replay, then replace it with your own complete tube layout.