Custom Room Shapes

While custom room shapes aren't technically part of the API yet, they can still be added by changing the API's data tables. (A function is planned for the master branch, and is already implemented in the experimental branch)

First, you must create the room's sprites and animations. There should be two sprites (small map and large map) for each state: Unvisited, Semivisited (Left room without clearing it), Visited and Current. If your room matches the size of any other room (eg 2x1), make sure that the crop x and crop y match the size of the base room (this is important for bounded map culling).

For examples on spriting rooms, see gfx/ui/minimap1.png in the game's resources, and gfx/ui/minimapapi/custom_minimap1.png in MinimapAPI's mod folder.

Once that has been created, create the sprite in lua:

local custommapsmall = Sprite()
custommapsmall:Load("gfx/mymod/custommapsmall.anm2", true)
local custommaplarge = Sprite()
custommaplarge:Load("gfx/mymod/custommaplarge.anm2", true)

(It doesn't matter how many sprites are used, putting all sprites on one sheet or using multiple is fine)

For this example, I'll assume we're adding a simple 1x1 room with the string ID "mycustomshape"

To get the API to render your sprites, you must enter the following:

MinimapAPI.RoomShapeFrames["mycustomshape"] = {
	small = {
		["RoomUnvisited"] = {sprite = custommapsmall,anim = "RoomUnvisited",frame = 0},
		["RoomVisited"] = {sprite = custommapsmall,anim = "RoomVisited",frame = 0},
		["RoomSemivisited"] = {sprite = custommapsmall,anim = "RoomSemivisited",frame = 0},
		["RoomCurrent"] = {sprite = custommapsmall,anim = "RoomCurrent",frame = 0},
	},
	large = {
		["RoomUnvisited"] = {sprite = custommaplarge,anim = "RoomUnvisited",frame = 0},
		["RoomVisited"] = {sprite = custommaplarge,anim = "RoomVisited",frame = 0},
		["RoomSemivisited"] = {sprite = custommaplarge,anim = "RoomSemivisited",frame = 0},
		["RoomCurrent"] = {sprite = custommaplarge,anim = "RoomCurrent",frame = 0},
	},
}

The "grid pivot" is top-left most occupied space of your room. For nearly all cases this is just (0,0).

MinimapAPI.RoomShapeGridPivots["mycustomshape"] = Vector(0,0)

The grid size is just the maximum width and height taken up by your room. L rooms would be (2,2), 2x1 rooms would be (2,1), for example.

MinimapAPI.RoomShapeGridSizes["mycustomshape"] = Vector(1,1)

The positions are every space taken up by your room. 2x2 rooms have 4 of these, L rooms have 3. (0,0) is the top left of your room. For this example, a 1x1 room would only have one grid space occupied.

MinimapAPI.RoomShapePositions["mycustomshape"] = {Vector(0,0)}

The position of each icon is stored below. The first table is for when there is only one icon, the second table is for more than 1. This is often a hassle to do (especially for large rooms), so I have given two examples, one is icon positions being copied from an existing room type and the other shows adding positions manually.

--copying from 1x1 room
MinimapAPI.RoomShapeIconPositions[1]["mycustomshape"] = MinimapAPI.RoomShapeIconPositions[1][RoomShape.ROOMSHAPE_1x1]
MinimapAPI.RoomShapeIconPositions[2]["mycustomshape"] = MinimapAPI.RoomShapeIconPositions[2][RoomShape.ROOMSHAPE_1x1]
--manual example
MinimapAPI.RoomShapeIconPositions[1]["mycustomshape"] = {Vector(0,0)}
MinimapAPI.RoomShapeIconPositions[2]["mycustomshape"] = {Vector(0,0)}

You must also do this for the large variant. (For large rooms, there is an extra table for icons >= 3).

--copying from 1x1 room
MinimapAPI.LargeRoomShapeIconPositions[1]["mycustomshape"] = MinimapAPI.LargeRoomShapeIconPositions[1][RoomShape.ROOMSHAPE_1x1]
MinimapAPI.LargeRoomShapeIconPositions[2]["mycustomshape"] = MinimapAPI.LargeRoomShapeIconPositions[2][RoomShape.ROOMSHAPE_1x1]
MinimapAPI.LargeRoomShapeIconPositions[3]["mycustomshape"] = MinimapAPI.LargeRoomShapeIconPositions[3][RoomShape.ROOMSHAPE_1x1]
--manual example
MinimapAPI.LargeRoomShapeIconPositions[1]["mycustomshape"] = {Vector(0.25,0.25)}
MinimapAPI.LargeRoomShapeIconPositions[2]["mycustomshape"] = {Vector(0,0.25),Vector(0.5,0.25)}
MinimapAPI.LargeRoomShapeIconPositions[3]["mycustomshape"] = {Vector(0,0),Vector(0.5,0),Vector(0,0.5),Vector(0.5,0.5)}

Finally, you must set adjacent coords for the room

• RoomShapeAdjacentCoords is a list of vectors that contain adjacent rooms, not in any order.
• RoomShapeDoorCoords is a list of adjacent room vectors but with the index of the corresponding DoorSlot + 1
• RoomShapeDoorSlots contains a list of DoorSlots that this room can have.

You can copy these if your shape matches that of an existing shape, but for this example I'm going to add a room type which can only be entered from the north side.

MinimapAPI.RoomShapeAdjacentCoords["mycustomshape"] = {Vector(0,-1)}
MinimapAPI.RoomShapeDoorCoords["mycustomshape"] = {[DoorSlot.UP0+1] = Vector(0,-1)}
MinimapAPI.RoomShapeDoorSlots["mycustomshape"] = {DoorSlot.UP0}

The room shape should now be implemented.

To add it onto a room, simply put your ID into the Shape index of the table in AddRoom:

MinimapAPI:AddRoom{Shape="mycustomshape"}