Cuts RoRender output into Roblox-uploadable tiles. Fully transparent tiles are never written, so the empty regions around a map's footprint cost you nothing.
cargo install rorender-chunk
rorender-chunk RoRender_Full_6151x9620.pngRoRender_Full_6151x9620.png
6151x9620 -> 7 cols x 10 rows | 65 tiles written, 5 empty skipped (7%) | 4.1 MiB | 0.25s
-> chunks/RoRender_Full_6151x9620
chunks/<render name>/
tile_r0_c2.png # row 0, column 2 -- 1024x1024 RGBA
tile_r0_c3.png
...
manifest.luau # grid metadata + every tile's source coordinates,
# as a Luau module with empty assetId slots
minimap.luau # world <-> pixel helpers, written once and never
# overwritten, so it is yours to edit
With --level, downscaled overview<factor>x_r#_c#.png tiles sit alongside the
base ones and get their own entry in the manifest. They are what you draw for a
full-map view, where the whole render has to be on screen but almost none of its
detail survives being scaled down — see Zoomed-out
levels.
Tiles are named by grid position, and positions of skipped tiles simply do not
appear — tile_r0_c0.png missing means that corner was empty.
Edge tiles are padded out to a full square with transparent pixels by default,
so every tile is exactly 1024x1024 and grid math in Roblox stays uniform. Pass
--no-pad to keep them at their natural size instead.
Upload the tiles, then in Studio's Asset Manager select them all at once,
right-click and click Copy Info. That puts a CSV table on your clipboard —
paste it into a text file and save it as assets.csv, header row included:
Name,Asset ID,Asset Type,Date Modified,Creator
tile_r0_c2,87362643947307,Image,1785990388349,YourName
tile_r0_c3,123360256974098,Image,1785990389478,YourName
Point apply-ids at the chunk folder and that file:
rorender-chunk apply-ids chunks/RoRender_Full_6151x9620 assets.csv
chunks/RoRender_Full_6151x9620/manifest.luau
65 tiles filled
every tile matched exactly one asset
Matching is by tile name, so upload order does not matter and the .png
extension is optional in the CSV. Tiles with no matching row keep whatever they
had and are listed as a warning; CSV rows matching no tile are reported too, so
a half-finished upload is obvious rather than silent.
Re-running is safe: it overwrites assetId values in place and touches nothing
else in the file, so applying the same CSV twice is a no-op. If you re-uploaded
a tile and have two rows with the same name, the one with the newer
Date Modified wins.
| Flag | Notes |
|---|---|
-o, --out <PATH> |
Write elsewhere instead of updating in place |
--bare |
Store 114661912512530 instead of rbxassetid://114661912512530 |
Then require the module to lay the grid out:
local grid = require(script.Parent.manifest)
for _, tile in grid.tiles do
local label = Instance.new("ImageLabel")
label.Image = tile.assetId
label.Size = UDim2.fromOffset(tile.w, tile.h)
label.Position = UDim2.fromOffset(tile.x, tile.y)
label.BackgroundTransparency = 1
label.Parent = container
endtile.x / tile.y are pixel coordinates in the original render, so scale them
by whatever factor your minimap frame uses.
The base tiles are the whole render at full resolution. That is what you want when the player is zoomed in on a street corner, and exactly what you do not want for a full-map view: showing all 65 of them at once means mounting 65 x 1024 x 1024 pixels, ~260 MB of texture memory, to draw a map that ends up a few hundred pixels wide on screen. Every one of those pixels is detail the player cannot see.
A full-map view needs the entire map present but barely any detail — the
opposite trade to a zoomed-in one. --level emits exactly that: a downscaled
copy of the render alongside the base grid, cut into the same tile size.
rorender-chunk RoRender_Full_6151x9620.png --level auto
RoRender_Full_6151x9620.png
6151x9620 -> 7 cols x 10 rows | 65 tiles written, 5 empty skipped (7%) | 4.1 MiB | 0.35s
level 4x -> 1538x2405 | 2 cols x 3 rows | 6 tiles written, 0 empty skipped | 1.6 MiB
-> chunks/RoRender_Full_6151x9620
Six images and ~25 MB of texture memory for the whole map, against sixty-five and ~260 MB. The 4x reduction does throw detail away, but this level is only ever on screen when the map is drawn smaller than the level itself, so what it threw away was not going to be visible.
The usual arrangement is to mount the base grid while the player is zoomed in far enough that only a few tiles are on screen, and switch to a level once the view pulls in more tiles than you are willing to hold in memory. Both grids share an origin and a tile size, so the switch is a swap of which images are parented, not a change of coordinate system.
auto picks the smallest power-of-two reduction that fits the whole render in
12 tiles (--level-budget changes the target), or nothing at all when the base
grid already fits — a render small enough to mount whole has nothing to gain
from a second copy of itself at half the detail. A whole-map view wants to land
somewhere around 6 to 12 tiles: few enough to be cheap, enough resolution that
the map does not look soft when it is the largest thing on screen. Pass a number
instead -- --level 4 -- if you want to choose, and repeat the flag for
intermediate steps: --level 2 --level 8, which is worth doing if your zoom
range is wide enough that one jump from full detail to the overview is visible.
Levels are sorted finest-first and de-duplicated, so order on the command line
does not matter.
Level tiles are named overview<factor>x_r{row}_c{col}.png, which keeps them
apart from the base tile_r#_c#.png and from each other. They upload and fill
in exactly like base tiles -- apply-ids matches every file in the manifest,
levels included.
They land in the manifest after tiles, finest first:
levels = {
{
source = "RoRender_Full_6151x9620.png reduced 4x",
scale = 0.25,
chunkSize = 1024,
columns = 2,
rows = 3,
tiles = {
{ row = 0, col = 0, x = 0, y = 0, w = 1024, h = 1024, file = "overview4x_r0_c0.png", assetId = "" },
-- ...
},
},
},scale is tile pixels per base map pixel -- not per pixel of whatever you
originally rendered from. A level's x / y / w / h are in its own reduced
pixels, so one multiply by 1 / scale puts them back on the base map's ruler
and placing a level becomes the base grid's loop with that factor applied:
local level = manifest.levels[1]
local perPixel = 1 / level.scale -- 4 base pixels per level pixel at scale 0.25
for _, tile in level.tiles do
local label = Instance.new("ImageLabel")
label.Image = tile.assetId
label.Size = UDim2.fromOffset(tile.w * perPixel, tile.h * perPixel)
label.Position = UDim2.fromOffset(tile.x * perPixel, tile.y * perPixel)
label.BackgroundTransparency = 1
label.Parent = container
endRead w / h off the tile rather than assuming chunkSize: under --no-pad
the edge tiles of a level are written at their natural size, exactly as they are
in the base grid.
Walk levels finest-first and step coarser only when the tile count a view
needs exceeds what you are willing to mount; the base tiles array is the
finest level of all.
Everything about a level lines up with the base grid on purpose. The reduced
image is padded out to whole chunks from pixel (0,0), the same origin, so
levels stay registered with each other and switching between them does not shift
the map -- an origin that differs looks fine until you cross the switch zoom and
then the map jumps. columns and rows describe that padded grid rather than
the reduced image's own size in chunks. Empty tiles are skipped here too, and
since the surface paints its own background, a missing cell looks the same at
every level.
The reduction is an integer box average, accumulated as the render streams past
rather than held whole. A level never buffers more than one grid row of its
reduced image -- ceil(width / factor) x chunkSize pixels, 6 MB for the 4x
level above -- because the moment a grid row's last reduced row is averaged it
is cut into tiles and the buffer is reused for the next one. That is what keeps
a level's cost flat in the height of the render instead of proportional to it:
a 24601x38477 render costs 50 MB at 2x rather than the 950 MB the whole reduced
image would take. Averaging rather than sampling is what keeps a 4x reduction
from aliasing detail into noise, and colour is averaged premultiplied by alpha,
so the transparent black outside the map's footprint cannot bleed a dark fringe
along its edge.
Reduction runs on the same bands the base cut already streams, alongside the base tiles' PNG encoding rather than after it, and spreads across the worker pool by reduced row -- so a level costs one shared pass over the pixels rather than a second decode of the render, and mostly hides behind work that was happening anyway.
Because the colour sums are 32-bit, --level tops out at 4096. A reduction
anywhere near that already puts the whole map in a single tile.
A grid of images is not a minimap until you can put a dot on it. Give the tool
the corners of the region you rendered -- the same two Vector3s you gave
RoRender -- and it works out the world-to-pixel mapping and stores it in the
manifest:
rorender-chunk calibrate chunks/RoRender_Full_6151x9620 \
--corner1 -3190.798,-195.207,-4487.743 \
--corner2 2958.456,1131.682,5131.023
chunks/RoRender_Full_6151x9620/manifest.luau
added calibration, 65 tiles untouched
region X -3190.798 .. 2958.456, Z -4487.743 .. 5131.023 | 1.000284 x 1.000128 px/stud
corners land at pixel 0.0,0.0 and 6151.0,9620.0 of 6151x9620
centre -116.171, 468.2375, 321.64 -> pixel 3075.5,4810.0
Asset IDs and everything else in the manifest are left alone, so calibrating an already-uploaded map is safe, and re-running replaces the block rather than stacking another one. The same flags work on a fresh cut if you have the numbers up front:
rorender-chunk RoRender_Full_6151x9620.png \
--corner1 -3190.798,-195.207,-4487.743 --corner2 2958.456,1131.682,5131.023
Vector3.new(-3190.798, -195.207, -4487.743) is accepted verbatim too, so a
line pasted out of your RoRender config or Studio's properties pane works.
| Flag | Notes |
|---|---|
--corner1, --corner2 <X,Y,Z> |
Opposite corners of the rendered region |
--world-center <X,Y,Z> |
Put this position at the image centre instead of the corners' midpoint |
--studs-per-pixel <N> |
Use a known scale; derived from the image size otherwise |
--flip-x, --flip-z |
The image runs the other way along that axis |
-o, --out <PATH> |
calibrate only: write elsewhere instead of in place |
The mapping assumes +X runs right across the image and +Z runs down it, which is
how Studio's top view shows a scene. If your markers come out mirrored, add
--flip-x or --flip-z.
locate is the quick way to check, without uploading anything or opening Studio.
Point it at somewhere you recognise -- spawn, a landmark, the corner of a
building -- and open the tile it names:
rorender-chunk locate chunks/RoRender_Full_6151x9620 -- 0,0,0
chunks/RoRender_Full_6151x9620/manifest.luau
6151x9620 render | X -3190.798 .. 2958.456, Z -4487.743 .. 5131.023 | 1.000284 x 1.000128 px/stud
world 0, 0, 0
pixel 3191.7, 4488.3 | scale 0.5189, 0.4666
tile_r4_c3.png (r4 c3) at 119.7, 392.3 within the tile -> rbxassetid://89146482112263
--pixel runs it backwards, turning a pixel you picked off the image in an
editor into the world position it corresponds to:
rorender-chunk locate chunks/RoRender_Full_6151x9620 --pixel -- 3075,4810
The -- keeps negative coordinates from being read as flags.
minimap.luau sits next to the manifest and does the arithmetic:
local Minimap = require(script.Parent.minimap)
local scale = Minimap.scaleToFit(frame.AbsoluteSize)
Minimap.render(frame, scale)
game:GetService("RunService").RenderStepped:Connect(function()
local root = player.Character and player.Character.PrimaryPart
if root then
marker.Position = Minimap.worldToOffset(root.Position, scale)
marker.Visible = Minimap.isInside(root.Position)
end
end)| Function | Returns |
|---|---|
worldToPixel(position) |
px, py in the full-size render |
pixelToWorld(px, py, y?) |
Vector3 |
worldToScale(position) |
0..1 fractions, for UDim2.fromScale |
worldToOffset(position, scale?) |
UDim2 for a marker over render(parent, scale) |
render(parent, scale?) |
The ImageLabels it parented |
scaleToFit(size) |
Scale that fits the whole render in size |
scaleForStudsPerPixel(studs) |
Scale at which a pixel covers studs studs |
studsPerPixel(scale?) |
World covered by one minimap pixel |
isInside(position), tileAt(position), tileAtPixel(px, py) |
Positions off the edge of the map come back as pixels outside the image rather than clamped, so a marker that should stay on screen is yours to clamp.
| Flag | Default | Notes |
|---|---|---|
-o, --out <DIR> |
chunks |
One subfolder per render |
-s, --chunk-size <N> |
1024 |
Roblox caps textures at 1024 |
--level <N|auto> |
none | Also emit a downscaled level for zoomed-out views; repeatable |
--level-budget <N> |
12 |
Tile count --level auto aims to fit the map into |
--no-pad |
off | Leave edge tiles at their natural size |
--alpha-threshold <N> |
0 |
Treat alpha <= N as transparent |
-c, --compression <LEVEL> |
default |
fast | default | best |
-j, --jobs <N> |
cores | Worker threads |
--dry-run |
off | Report the tile plan without writing |
--flat |
off | All tiles into --out, no per-render subfolder |
-q, --quiet |
off | No per-band progress |
Inputs can be files or directories; a directory is scanned for renders and each one is processed in turn.
--alpha-threshold is worth knowing about: if a render has faint anti-aliasing
noise over otherwise empty ground, --alpha-threshold 8 or so will discard
those near-invisible tiles too.
The render is consumed in horizontal bands one tile tall. A reader thread fills
the next band while the worker pool slices the current one, and band buffers are
recycled through a channel rather than reallocated. Peak memory therefore tracks
the render's width, not its area — roughly width x chunk_size x 4 x 3 bytes.
On the 6151x9620 sample that is ~109 MB peak instead of the 226 MB a full decode would need, and the gap widens with size: a 20000x20000 render needs ~245 MB here versus 1.6 GB decoded whole.
Transparency scanning reads two pixels at a time as a u64 masked against
0xFF000000FF000000 and bails on the first visible pixel, so empty regions are
rejected almost for free.
PNG is decoded row by row. Palette, grayscale, 16-bit and no-alpha PNGs are all normalized to RGBA8 on the way in; a render with no alpha channel skips the emptiness check entirely since none of its tiles can be blank. Interlaced PNGs have no usable row order, so they fall back to a whole-image decode, as do non-PNG inputs (jpg/tiff/webp/bmp).
The world mapping is anchored at the centre of the image rather than at a corner.
RoRender rounds its pixel dimensions up, so the region and the image rarely match
to the pixel — 6149.254 studs across becomes 6151 pixels above. Anchoring at the
centre keeps that slack split evenly instead of piling it up at one edge, and it
is what lets --studs-per-pixel describe a render with a margin around the
region. With the scale derived from the image instead, the two are equivalent:
the corners land exactly on the image corners.
cargo test --release
Covers the alpha-scan fast path against a naive reference (including the
odd-width tails the u64 path cannot cover and the --alpha-threshold
boundary), plus CSV parsing: quoted fields, embedded commas, doubled quotes,
header-name variants and duplicate-upload resolution.
Levels are covered for the box average itself (whole blocks, short edge blocks,
and that feeding the reducer band by band matches one shot), plus auto's tile
budget and the finest-first ordering.
The calibration side covers coordinate parsing, world/pixel round trips (with
flips, and for positions off the map), the corner and centre landing points, and
that writing a world block into a manifest leaves the asset IDs alone and is
idempotent.