Authoring Layouts ItemGrid

Authoring Layouts — Item Grid

An item grid is a regular grid of tracked items declared row-by-row, with shared item sizing and margins. It's the workhorse element for the main items area of nearly every pack — when you want N rows of M items, all the same size, this is the right tool.

See Authoring Layouts for the file format and base fields. This page only covers fields specific to the itemgrid type.

JSON schema

Parsed in EmoTracker.Data/Layout/ItemGrid.cs, which delegates to EmoTracker.Data/Items/ItemGrid.cs:Load. Matches the itemgrid branch in layouts.json.

Field	Type	Required	Default	Description
type	"itemgrid"	yes	—	Literal string.
rows	array of arrays of strings	yes	—	Each entry is a row; each string in a row is an item code. Use empty strings or Blank item codes for grid spacers.
item_size	number	no	32	Pixel size used for both item width and height.
item_width	number	no	item_size	Overrides item width.
item_height	number	no	item_size	Overrides item height.
item_margin	string	no	"5"	Margin around each item — uses the same 1/2/4-number comma syntax as the base margin field.
badge_font_size	number	no	12	Font size used for item badges (e.g. consumable counters).

Plus the standard base fields from Authoring Layouts → Fields every layout element shares.

Legacy margin field. Older packs used the base margin field on itemgrid to mean "margin between items" rather than "outer margin around the grid". The runtime preserves that behavior for packs declared with an older LayoutEngineVersion. New packs should use item_margin (clear meaning) and reserve the base margin for outer spacing.

How rows are parsed

Each entry in rows is parsed via ItemDatabase.FindProvidingItemForCode for every code in the row. The grid renders rows top-to-bottom and items left-to-right within each row. Rows can have different lengths — the layout doesn't enforce equal column counts, so a 3-item row sits next to a 5-item row without padding (you can pad manually with Blank items).

Examples

A 3×4 items grid

{
  "type": "itemgrid",
  "item_size": 32,
  "item_margin": "3",
  "rows": [
    [ "sword",    "shield",   "bow",      "boomerang" ],
    [ "hookshot", "lamp",     "hammer",   "shovel"    ],
    [ "fluteact", "bugnet",   "book",     "bottle"    ]
  ]
}

Mixing item sizes via separate grids

When you need different sizes within the same visual area, use multiple grids inside an Array:

{
  "type": "array",
  "orientation": "vertical",
  "content": [
    {
      "type": "itemgrid",
      "item_size": 32,
      "rows": [ [ "sword", "shield", "bow" ] ]
    },
    {
      "type": "itemgrid",
      "item_size": 24,
      "rows": [
        [ "ep_prize", "dp_prize", "th_prize", "pd_prize" ]
      ]
    }
  ]
}

Padding rows with blanks

If a row has fewer items than the others and you want it visually centered or padded, use a Blank item code in the gap, or just include "":

{
  "type": "itemgrid",
  "rows": [
    [ "sword",    "shield",   "bow" ],
    [ "blank_a",  "hookshot", ""    ]
  ]
}

Tips and pitfalls

• Codes must resolve to existing items. Empty / unknown codes leave the cell empty in the grid. Use Tracker:AddItems(...) for all relevant items before loading the layout that references them.
• item_size is the simplest knob. Set just item_size for a uniform grid; use item_width / item_height only when you need non-square items.
• For irregular layouts (mixed sizes, gaps, overlapping), prefer Array or Canvas. Item Grid only handles regular grids.
• Different rows can have different lengths. The grid doesn't pad short rows automatically; explicit blanks are the standard way to align them visually.
• badge_font_size controls counter text size — bump it up for consumables with multi-digit counts.

See also

• Authoring Layouts — top-level format and base fields
• Authoring Layouts — Item — a single item by itself
• Authoring Items — how items are declared
• Authoring Items — Blank — placeholder items used for grid spacing
• layouts.json schema — authoritative JSON schema