-
Notifications
You must be signed in to change notification settings - Fork 67
Layouts
Working with x-y coordinates all the time can be tiresome, and ideally everything in a game prototype should be data-driven and easily changed. For this, many Squib methods allow for a layout
to be set. In essence, layouts are a way of setting default values for any argument given to the command.
To use a layout, set the layout:
option on a Deck.new
command to point to a YAML file. Any command that allows a layout
option can be set with a Ruby symbol or String, and the command will then load the specified x
, y
, width
, and height
. The individual command can also override these options.
Instead of this:
# deck.rb
Squib::Deck.new(layout: 'custom-layout.yml') do
rect x: 75, y: 75, width: 675, height: 975
end
You can put your logic in the layout file and reference them:
# custom-layout.yml
frame:
x: 75
y: 75
width: 975
height: 675
Then your script looks like this:
# deck.rb
Squib::Deck.new(layout: 'custom-layout.yml') do
rect layout: 'frame'
end
The goal is to make your Ruby code more separate data from logic, which in turn makes your code more readable and maintainable. With extends
(see below), layouts become even more powerful in keeping you from repeating yourself.
Note: YAML is very finnicky about not allowing tab characters. Use two spaces for indentation instead. If you get a Psych
syntax error, this is likely the culprit. Indendation is also strongly enforced in Yaml too. See the Yaml docs.
Layouts will override Squib's system defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
- Use what the command specified
- If anything was not yet specified, use what was given in a layout (if a layout was specified in the command and the file was given to the Deck)
- If still anything was not yet specified, use what was given in Squib's defaults.
Squib provides a way of reusing layouts with the special extends
key. When defining an extends
key, we can merge in another key and modify data coming in if we want to. This allows us to do things like place text next to an icon and be able to move them with each other. Like this:
# If we change the xy of attack, we move defend too!
attack:
x: 100
y: 100
radius: 100
defend:
extends: attack
x: += 50
#defend now is {:x => 150, :y => 100}
If you want to extend multiple parents, it looks like this:
socrates:
x: 100
plato:
y: 200
aristotle:
extends:
- socrates
- plato
x: += 50
If multiple keys override the same keys in a parent, the later ("younger") child takes precedent.
Note that extends keys are similar to Yaml's "merge keys". With merge keys, you can define base styles in one entry, then include those keys elsewhere. For example:
icon: &icon
width: 50
height: 50
icon_left
<<: *icon
x: 100
# The layout for icon_left will have the width/height from icon!
If you use both extends
and Yaml merge keys, the Yaml merge keys are processed first, then extends. For clarity, however, you're probably just better off using extends
exclusively.
Squib also supports the combination of multiple layout files. If you provide an Array
of files then Squib will merge them sequentially. Colliding keys will be completely re-defined by the later file. Extends is processed after each file. Here's a complex example:
# load order: a.yml, b.yml
##############
# file a.yml #
##############
grandparent:
x: 100
parent_a:
extends: grandparent
x: += 10 # evaluates to 110
parent_b:
extends: grandparent
x: += 20 # evaluates to 120
##############
# file b.yml #
##############
child_a:
extends: parent_a # i.e. extends a layout in a separate file
x: += 3 # evaluates to 113 (i.e 110 + 3)
parent_b: # redefined
extends: grandparent
x: += 30 # evaluates to 130 (i.e. 100 + 30)
child_b:
extends: parent_b
x: += 3 # evaluates to 133 (i.e. 130 + 3)
This can be helpful for:
- Creating a base layout for structure, and one for color (for easier color/black-and-white switching)
- Sharing base layouts with other designers
YAML merge keys are NOT supported across multiple files - use extends
instead.
Why mess with x-y coordinates when you're first prototyping your game?!?!? Just use a built-in layout to get your game to the table as quickly as possible.
If your layout file is not found in the current directory, Squib will search for its own set of layout files. The latest the development version of these can be found on GitHub. The layouts_builtin.rb
sample (found here) demonstrate built-in layouts based on popular games (e.g. fantasy.yml
and economy.yml
)
Contributions in this area are particularly welcome!
This sample demonstrates many different ways of using and combining layouts. This is the layouts.rb
sample found here
{include:file:samples/layouts.rb}
Install: Windows OSX Linux Cygwin
Getting Started
Important
Advanced Squibbing
- The Mighty text Method
- Layouts
- Manipulating PNGs
- Manipulating SVGs
- Vector back end
- Rendering both BW and Color
- Colors
- Configuration Options
Real Project Histories
Squiblets
- Category specific template text
- Combining Multiple Columns
- One Icon Per Location
- One Location, Multiple Icons
- Google Sheets
- Rake Rendering Modes
- Autoscale Fonts
- Marketing Materials
- Autobuild with Guardfiles
- Wireframing with an SVG Editor
- Front to Back Printing
- Versioning Practices
- Icon Library: FontAwesome
- Icon Library: GameIcons
- Combining Multiple Columns
- Combine Multiple CSV Files
- Switch card background or invert theme
Tools
Contributing