Skip to content

About

Cuts RoRender output into Roblox-uploadable tiles for minimap generation

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

rorender-chunk

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.png
RoRender_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

Output

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.

Filling in asset IDs

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
end

tile.x / tile.y are pixel coordinates in the original render, so scale them by whatever factor your minimap frame uses.

Zoomed-out levels

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
end

Read 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.

Calibrating to world space

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

Getting it right

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.

Using it in game

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.

Options

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.

How it works

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.

Tests

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.

About

Cuts RoRender output into Roblox-uploadable tiles for minimap generation

Resources

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages