Contained Type enables code generation and Gum runtimes (such as FlatRedBall) to create strongly-typed containers.
Some Gum components or Containers may exist to hold a list of a particular type of item. For example, consider a game which includes a row of hearts to show the player's current health.
In this particular case, the hearts can be filled or empty to show the current and max health, but the max health can also be increased. If the max health increases, then a new heart instance is added to the container at runtime.
Since this container should only ever contain instances of a Heart component, then the container's Contained Type can be set to Heart.
In this example, FlatRedBall respects the Contained Type variable and generates a generic list.
As mentioned above, the implementation of this variable depends on the runtime you are using. If you are using a runtime which does not implement this feature and you would like to have it added, please create a GitHub issue or make a request in Discord.
Children Layout determines how a container positions its children. The default value is Regular which means that children are positioned according to their X Units and Y Units.
Top to Bottom Stack results in the children stacking one on top of another, from top to bottom.
Left to Right Stack results in the children stacking one beside another, from left to right.
Auto Grid Horizontal results in the children being placed in a grid, filling in horizontally first before wrapping to the next row.
Auto Grid Vertical results in the children being placed in a grid, filling in vertically first before wrapping to a new column.
The following animation shows how to use the ChildrenLayout variable to change the default position of a Container's children:
Regular layout positions each child independent of every other child. The position of one child does not affect the position other children. This is the default layout for containers.
Top to Bottom Stack results in each child being positioned after its previous sibling vertically. This can be used to create horizontal stacks.
Top to Bottom Stack behaves similarly to Left to Right Stack. For a detailed discussion see the Left to Right Stack section below.
Left to Right Stack results in each child being positioned after its previous sibling horizontally. This can be used to create vertical stacks.
A container can stack its children and also have its size based on its children. This results in the container growing as children are added.
For example, the following shows a container with its Height Units set to Relative To Children and its Children Layout set to Top To Bottom Stack. As more children are added the container grows vertically.
If the container also has a Max Height (or a Max Width in a Left to Right Stack), it grows until it reaches that value. A child that crosses the max stays in the stack and extends past the container's edge. If Wraps Children is checked, that child moves to a new column (or row) instead, so the container stops at the last child that fits. For more information see the page.
Invisible children are ignored in the stack, so toggling the Visible property removes a child from the stack.
When children stack, each child's X or Y depends on the boundary of its previous sibling. When stacking vertically, the child's Y value begins at the bottom side of the previous item. Similarly, when stacking horizontally, the child's X value begins at the right side of the previous item.
For example, the following image shows a Text object with a Y value of 20. Notice that it is positioned 20 units below the item above it.
This effect is easy to notice when dragging an object inside a stack, as shown in the following animation:
If instances are stacked in a container, the stacking controls the instance values based on the direction of the stack.
Top to Bottom Stack containers control the Y value of their children.
Left to Right Stack containers control the X value of their children.
The position value which is not controlled by the stack can be changed freely without any impact on the stacking.
The first child in a stack uses its units and origin on the stacking axis like any other child. Every child after the first ignores them, so the stack always places it right after its previous sibling:
In a Top to Bottom Stack, later children measure Y from the bottom of the previous sibling whatever their Y Units, and treat Y Origin as Top.
In a Left to Right Stack, later children measure X from the right side of the previous sibling whatever their
The child's X or Y value still applies, and adds space between the child and its previous sibling. For more information see the section below.
For example, if a container stacks its children using a Top to Bottom Stack, the children in the stack are free to change their X values. The following animation shows how children can be left, center, or right anchored (which changes their X Units and X Origin) without affecting the other children in the stack.
Top to Bottom Stack and Left to Right Stack separate their children using the Stack Spacing value. For more information, see the page.
The position of a child in a stack is determined by the size of the previous item in the stack. Consider a container with a blue rectangle which stacks horizontally. The blue occupies some space according to its absolute width. The next instance after the blue rectangle is placed relative to the right side of the blue rectangle.
For example, if a red rectangle (partially transparent to make it easier to see when overlapping) is added to the container, the stack creates a layout similar to the following image:
The red rectangle stays in this position even if its is Center or Right. A child after the first ignores its origin on the stacking axis, so it never overlaps its previous sibling. Its origin on the other axis works normally, so a child in a Top to Bottom Stack can still center itself horizontally.
The first child in a stack uses its origin on both axes.
A stack places the next child after a rotated child as if the rotated child were not rotated. With the default Top and Left origin, a rotated child turns about its top-left corner, so it can overlap its neighbors or leave gaps.
With another origin, such as Center, the rotation also shifts where the next child starts. A rotated child in an Auto Grid Horizontal or Auto Grid Vertical container turns within its own cell and never moves the other cells.
The property controls how stacking behaves beyond boundaries. For more information, see the page. In a wrapping stack, each row or column is the parent of its children on the other axis for positioning, so a centered child centers in its row. For more information see .
Children of a container which uses the Top To Bottom Stack or Left To Right Stack are ordered according to their order in the tree view on the left. By default this is the order in which the children are added to a parent container.
Children can be reordered using the right-click menu on an instance.
Alternatively, children order can be changed by clicking on the item in the tree view, holding down the ALT key, then pressing the up or down arrows.
For more information on ordering, see the page.
Auto Grid Horizontal and Auto Grid Vertical layouts result in each child of the container being placed in its own cell. All position and size values are relative to the entire cell, so children can expand to fill their cell or be positioned according to any side or corner.
The following image shows a container with 4x4 auto grid. Each child is positioned relative to the top-left corner of each grid. In this case, each child has an Absolute Width and Height of 50 and the parent container is sized 256x256. This results in each rectangle leaving a gap between itself and its neighbor.
The following shows a container with an Auto Grid Horizontal and Vertical Cells of 2, resulting in a 2x2 grid. As children are added to the container through copy/paste, each child is placed in its own cell.
The number of cells is controlled by the Auto Grid Horizontal Cells and Auto Grid Vertical Cells. Increasing the number of cells results in the rows or columns adjusting automatically.
Each child occupies one cell, and the order of the children controls the order of the placement in grids. The first child occupies the top-left row. If using Auto Grid Horizontal, each child is placed to the right of its preceding sibling, wrapping to the next line when reaching the end of a row. If using Auto Grid Vertical, each child is placed below its preceding sibling, wrapping to the next column when reaching the end of a column.
Children can be reordered by using the alt+arrow key in the tree view, resulting in reordering just like when using a stacking Children Layout.
Children treat their particular cell in the grid as their parent, so any sizes or positions will be based on their parent cell. In other words, if a child's Width Units is set to Relative To Parent, the parent in this case is the cell, not the entire Container instance.
The number of cells in a grid is determined by multiplying Auto Grid Cells Horizontal by Auto Grid Cells Vertical. If a container has more children than its total cells and if the container's size does not depend on its children, additional children spill over the bounds of the grid. The following animation shows a 3x3 grid using Auto Grid Horizontal. As more children are added, additional rows are added below the bounds of the grid.
If the container has its Width Units or Height Units set to Relative To Children, then its size may adjust in response to adding more children. For more information, see the and pages.
When using Auto Grid Horizontal, the number of columns is fixed, but additional rows can be added beyond the bounds of the container.
When using Auto Grid Vertical, the number of rows is fixed, but additional columns can be added beyond the bounds of the container.
Stack Spacing can be used to separate cells in a grid. This is most commonly used when the grid's children use Width Units or Height Units of Relative to Parent.
The following shows a grid with children which fill their cells. Changing the Stack Spacing adds gaps between each child.
If a container's Children Layout is set to Auto Grid Horizontal or Auto Grid Vertical, it can size itself according to the largest cell by using Width Units or Height Units of Relative To Children. For more information see the and pages.
X UnitsX OriginLeftBreaking change in November 2026: Before this version, a stack without Wraps Children stopped growing at the last child that fit under its max, the same as a wrapping stack, so it could end up smaller than its max. Available in November 2026, or now if building Gum from source. For more information see Migrating to 2026 November.
Breaking change in November 2026: Before this version, a later child's X Origin (in a Left to Right Stack) or Y Origin (in a Top to Bottom Stack) moved it back over its previous sibling. A Center origin overlapped the previous sibling by half the child's size, and a Right or Bottom origin overlapped it completely. Available in November 2026, or now if building Gum from source. For more information see Migrating to 2026 November.
Stacking with rotation may become more sophisticated in a future version of Gum, so this behavior may change.
The Wraps Children property controls whether children wrap or stack beyond their container's boundaries when the container's Children Layout is set to Top to Bottom Stack or Left to Right Stack.
If a parent has Wraps children set to true, the wrapping adjusts in response to resizing the parent.
Similarly, resizing a child may result in the stacking changing.
The row height in a Left to Right Stack is determined by the largest child in the row.
Similarly, column width in a Top to bottom Stack is determined by the largest child in the column.
In a wrapping stack, each row (in a Left to Right Stack) or column (in a Top to Bottom Stack) acts as the parent of its children on the other axis. A child's Y Units and Y Origin in a Left to Right Stack, or its X Units and X Origin in a Top to Bottom Stack, position it within its row or column instead of within the whole container:
Pixels From Center with a Center origin centers the child in its row or column.
Pixels From Bottom (or Pixels From Right) with a Bottom (or Right) origin aligns the child to the far edge of its row or column. Pixels From Baseline uses the bottom of the row.
A row or column is as large as its largest child, and rows and columns stay packed at the start of the container. They do not stretch to fill extra space. Because of this, a child alone in its row is the same size as its row, so centering it or aligning it to the far edge leaves it at the start of the row.
A row counts each child the same way a container with Height Units of Relative to Children does (see ):
An X or Y value counts from the edge it is measured from. For example, a child placed 10 pixels up from the bottom of its row makes the row 10 pixels taller than the child.
A portion of a child placed outside its row does not make the row larger.
A child positioned with Percentage does not count toward its row's size.
Size units are unaffected. A child with Height Units of Percentage of Parent or Relative to Parent still sizes itself from the whole container, not its row.
Stacks that do not wrap position children on the other axis within the whole container.
Wrapping of children can only be performed if the parent's size does not depend on its children (see more info below). If the parent's size does depend on its children, then the parent will expand to fit is children so wrapping will not occur.
If a parent container's Width Units is set to Relative to Children, then it adjusts in response to children size and positioning, so wrapping will not occur.
A parent can use the following Width Units and Height Units with children wrapping:
✅Absolute
✅Percentage of Parent
✅Ratio of Parent
✅Percentage of Width/Height
A parent does not wrap its children if it uses:
❌Relative to Children (see below)
Note that Relative to Children can be used on the non-stacking axis. For example, if a parent uses Left to Right Stack, then it can still have its Height Units set to Relative to Children.
If a container has a non-null Max Width, then it will expand according to its children until it reaches its max width. Once it reaches a max width, it wraps its children.
The max width applies after the container's Width padding is added, so the padding can shrink when the children fill a row. Rows do not wrap earlier to keep the padding.
The container is as wide as its widest row. Each row breaks where the next child would pass the max width, so a later row can be wider than the first. For example, with a Max Width of 200, children 100, 120, and 60 wide make two rows, the first holding the 100 wide child and the second holding the other two, and the container is 180 wide.
The following animation shows a container which has:
Width Units of Relative to Children
Max Width of 400
Children Layout of Left to Right Stack
Wraps Children set to True
Percentage places the child at a percentage of its row or column's size.
Pixels From Top (or Pixels From Left) places the child relative to the start of its row or column.
A child whose size depends on its parent, such as Percentage of Parent, counts toward its row's size when the container's own size on that axis does not depend on its children. For example, in a Left to Right Stack that is 300 tall, tiles with Height Units of Percentage of Parent and Height of 30 make each row 90 tall. If the container's Height Units is Relative to Children, such a child does not count, because the container and the child would each depend on the other.
Breaking change in November 2026: Before this version, a child in a wrapping stack was positioned within the whole container on the other axis, so a centered child was centered in the container rather than in its row or column. Available in November 2026, or now if building Gum from source. For more information see .
Breaking change in November 2026: Before this version, the container measured only its first row, so later rows wrapped against that narrower width and a wider child could extend past the container. Available in November 2026, or now if building Gum from source. For more information see .
Is Render Target controls whether all instances contained in this container render directly to the screen (if false), or if they first render to their own dedicated target before rendering to the screen (if true).
Is Render Target defaults to false (unchecked).
Is Render Target enables a number of graphical effects including:
Container Alpha (transparency)
Container
Alpha-only modes on instances contained in the Container
Containers with Is Render Target set to true automatically clip their children. This behavior is the same as setting to true. This happens because render targets internally create a texture which matches their size. Therefore, any items which are placed outside of the bounds of a render target container are not rendered.
Once a container is rendered to a render target, additional special effects can be applied at runtime. These include:
Scaling
Rotating
Rendering portions using texture coordinates
For a step-by-step tool walkthrough of rotating and scaling a clipped container, see . For the same pattern in code, see the documentation.
If you are managing a render target yourself in code instead of using Is Render Target, see for the blend-mode setup needed to composite translucent content correctly on MonoGame and raylib.
The Stack Spacing variable controls the additional padding between children when a container uses a Children Layout of either Top to Bottom Stack or Left to Right Stack. Stack Spacing serves as an alternative to adjusting the position of each item in a stack.
A larger Stack Spacing value increases the spacing between each child. By default Stack Spacing is set to 0 which means that no spacing is added between items in a stack.
Changing the stack spacing adds gaps between each child as shown in the following animation.
Stack Spacing can also be a negative value resulting in overlapping children. The items in the following animation are partially transparent to show the overlap.
Stack Spacing can be used for either Top to Bottom or Left to Right Stacking.
Stack Spacing can be used on container instances which stack and wrap their children. As stack spacing increases, the amount of space allocated to each object also increases, resulting in wrapping occurring earlier.
If wrapping occurs, then stack spacing applies spacing between rows and columns as shown the following animation:
As of February 2025 the Is Render Target variable is considered experimental. You may experience issues when using this as it is being developed. Please report any problems you find through GitHub or on Discord.
Containers are used to group objects to simply movement, alignment, positioning, and size. Containers are usually invisible, although they can draw their outlines in Gum to help visualize their position and size.
