Ball Sort Tube JSON Format Guide
Tube JSON is a small text copy of a Ball Sort board. The outer array is the full level. Each inner array is one tube, and every value inside it is one separate ball.
Quick answer
Write every tube from bottom to top
The first value is the bottom ball, the last value is the exposed top ball, and a completely empty tube is []. In the current Solver, capacity is 4 and every color must appear exactly 4 times.
Include every tube, even when it is empty. Leaving out a spare tube changes the puzzle that the Solver searches.
What Each Part of the JSON Means
[The full board begins[1, 2, 3, 1],Tube A, bottom to top[2, 3],Tube B, partly filled[]Tube C, completely empty]The full board endsnull, zeros, or blank strings to fill the remaining slots.A Complete Valid Ball Sort Example
This is the example used on the current Ball Sort Solver page. It has three colors, four balls of each color, and two empty tubes.
[
[1, 2, 3, 1],
[2, 3, 1, 2],
[3, 1, 2, 3],
[],
[]
]Tube A ends in 1, so color 1 is its exposed top ball.
The Last Value Is the Top Ball
Tube A
Correct order
[4, 2, 1]The Solver can remove only the final value, so 1 is the next ball that may move.
Writing [1, 2, 4] does not cause a JSON error. It describes a different tube with color 4 on top.
Write Every Empty Tube as []
An empty tube is part of the level. It gives the puzzle working space and changes which moves are possible. The current Ball validator also requires at least one explicit empty tube before Solve is enabled.
[
[1, 2],
[2, 1],
[]
]The last inner array records the empty tube.
[
[1, 2],
[2, 1]
]The board now has one fewer tube and fails the empty-tube check.
[null, null]null is not an empty slot. It is an unsupported ball value.
[0, 0]Zero is a valid numeric color ID, so this means two balls of color 0.
The Checks the Current Ball Solver Makes
These are tool rules, not a claim that every Ball Sort game on the web uses the same setup. The current SortingGames.io Solver supports standard capacity-four levels.
| Check | Current rule | What to do |
|---|---|---|
| Tube capacity | 0 to 4 balls in each tube | Remove placeholders and recheck overfilled tubes |
| Color count | Exactly 4 balls for every color | Recount similar shades across the whole board |
| Empty tube | At least one tube must be exactly [] | Include all empty tubes shown in the level |
| Number of tubes | No more than 32 | Use only the current level, not an archive or several boards |
| Color values | Finite numbers or non-empty strings up to 32 characters | Use short, consistent IDs |
| Move meaning | One final array value moves per action | Do not group touching balls into one value |
If a color appears three or five times, search does not start. This is stricter than the current Water Sort Solver, where a count other than four is shown as a warning but does not by itself block search.
JSON Shapes the Parser Accepts
A direct top-level array is the clearest choice for manual entry. The parser also accepts a few object shapes used by other parts of the site.
| Shape | Example | Meaning |
|---|---|---|
| Direct array | [[1,2],[]] | The top-level value is the tube list |
| tubes wrapper | {"tubes":[[1,2],[]]} | The tubes property holds the list |
| bottles wrapper | {"bottles":[[1,2],[]]} | Accepted as a tube list even though “tubes” is clearer |
| level wrapper | {"level":[[1,2],[]]} | The level property holds the list |
| data wrapper | {"data":[[1,2],[]]} | The data property holds the list |
| Tube object | {"balls":[1,2]} or {"colors":[1,2]} | An individual tube stores its ball array in a property |
Keep Color IDs Simple and Consistent
Numbers
Easy to enter
[
[1, 2, 1],
[2],
[]
]Use the same number every time the same color appears. Different colors need different IDs.
Names
Easy to remember
[
["blue", "red"],
["red", "blue"],
[]
]Short strings work too. Keep spelling and case consistent so the preview and counts are easy to check.
Do not change one color from 1 to "1" halfway through the board. The parser normalizes color matching through its text form, but one clear style avoids confusing input and makes manual review easier.
Why Ball and Water JSON Can Look the Same
Both tools use nested arrays and both read each container from bottom to top. That shared shape describes a stack. It does not make the move rules the same.
| Same array | Ball Sort meaning | Water Sort meaning |
|---|---|---|
[2, 1, 1] | Three separate balls; the final 1 is the only ball moved now | Three liquid layers; the two connected top 1 layers may pour together |
[] | An empty tube | An empty bottle |
| Final value | The exposed top ball | The exposed top liquid layer |
Use the Water Sort vs Ball Sort comparison for the full move example. If your puzzle contains liquid bands, follow the separate Water Sort Bottle JSON Guide.
Common Ball Sort Input Mistakes
- Reading top to bottom: reverse the inner array so the top ball is last.
- Leaving out an empty tube: add one
[]for every empty tube in the game. - Merging matching balls: repeat the color ID once for each separate sphere.
- Mixing close shades: choose a different ID only when the balls are truly different colors.
- Using placeholders: open slots do not need values.
- Entering hidden colors: the Solver does not support unknown or covered ball values.
- Using another capacity: the current Ball Solver is fixed at 4.
- Expecting screenshot reading: the Solver itself reads JSON, not images.
Preview the Board Before Solving
Paste the finished JSON into the Solver and select Load JSON. Compare the preview tube by tube. Check the top ball, the order below it, the empty tubes, and the color-count result before starting a search.