The table, along with the cards, are the visual part of Sunflower games. The table determines what the screen will look like while the game is played, and how the user interacts with it. This is meant to allow a complete separation between visuals and logic – the game rules defined by the ruleset can be played on any interface, theoretically we can develop text-based or audio-based or smell-based interfaces if we want, without changing the rulesets. And this way, different people can play on different tables if they wish, while still playing the same game.
The table, much like the ruleset, is a simple XML file. It starts with an XML declaration:
<?xml version=”1.0″ encoding=”UTF-8″ ?>
And moves to the root element, which is <table>.
An important thing to note about tables is that, at least for the initial version, each table fits exactly to the size of the screen. There are no camera movements. For this reason, all sizes and positions are defined not in pixels or centimeters, but in fractions of the screen size. So for example, a rectangle whose width is 0.6 and height is 0.3, will in practice have a width of 60% of the screen width, and a height of 30% of the screen height.
First of all, we need to synchronize between the table size and the card sizes. Remember that the card appearences are defined in image files that may be of various sizes, and we need to resize them to fit our table design. So the first thing we do is define the card size. We have three tags for that: <cardheight>, <cardwidth>, and <cardsizeratio>. Only two of those should be defined – usually you’d want to choose either width or height, and then scale the cards accordingly. <cardsizeratio> is the product of dividing the card height by its width (so for most cards, it will be a number between 0 and 1). If you prefer to define height and width instead – the cards will be streched as needed to fit both numbers. Remember – width is defined as a fraction of the screen width, and height is a fraction of screen height.
The easiest way to handle the visual part of the table is to draw an image and save it into a file in the resources/table/images folder. Then you’ll want to create an <image> tag with the file name. The name may include a path – it’s assumed to be in resources/table/images, so if you wish you create subfolders. You may use either forward slash or backward slash in the file paths, the engine will convert it if necessary.
Next comes the most important part, the zones. I mentioned the zones in my description of rulesets, and it’s important to understand the difference between the actual zone, defined in the ruleset, and the visual representation of the zone, defined in the table. A zone does not have to exist in the table to be part of the game – if a zone is not defined in the table, then any card that moves to it will simply not appear on the screen unless moved back to a zone that is on the table. This is common, for example, when discarding cards – often when a card is discarded it has no more effect on the game unless returned in some way, and thus there might not be any benefit to showing it on the screen. The opposite is also true – a zone may be defined in the table but not in the ruleset. This means the zone will be purely aesthetical, and no cards may be placed on it. You’ll want to do that if you want to add some visuals in some part of the table, or make a special place for messages to the user.
For now, zones may only be axis-aligned rectangles. Future versions might allow more flexibility.
Zones are defined under the <zones> tag, and each is a <zone> tag. Inside it are 5 mandatory tags:
-<id> is a string identifier of the zone, which must be unique. If the zone is a visual representation of a zone from the ruleset, their IDs must be the same.
- <x> and <y> are the location of the zone on the screen. Remember that x values are defined as fractions of the screen width, and y values are defined as fractions of the screen height.
- <width> and <height> are the size of the zone. Again, width is defined as a fraction of the screen width, and height a fraction of the screen height.
Important: Zones may not overlap. The behaviour in case of overlapping zones is undefined.
In addition, zones have several optional subtags, for defining two things: What they look like, and how cards are ordered inside them.
If you made an image for your table, you don’t need to worry about appearance tags for each zone. However, if you prefer, you may put a special <image> tag for a zone. The tag has the same syntax as the <image> tag for the entire table, and the image will be centered in the middle of the zone. If you have both a table image and a zone image, the zone image will be drawn after the table image.
Also, you may get an automatic image, where each zone will just be painted in a certain color. For that, just add a <hue> tag, with a number between 0 and 1 representing the hue. Use hue -1 to paint it solid black. The automatic image might not be amazing, but it’s practical. And it’s especially useful in the beginning, when you just want to test your game without yet making amazing graphics.
Finally, you can use a <layout> tag to define how cards are ordered in the zone. Players can move cards within zones whichever way they want (unless you explicitly disable that), but the layout determines how cards are placed when moved between zones automatically by the engine. The default is the deck layout, which just has all cards stacked on top of one another in the middle of the zone. A full list of available layouts will be published later.
After defining zones, the last thing remaining is messages. Messages are simply text shown to the user, though in the future there will be more options. The messages are defined as scripts, so you can show the value of any variables as needed. The messages are under the <messages> tag, and are defined in a <message> tag with the following subtags:
- <x> and <y> are the message location. Like zones, this is defined in fractions of the screen width (for x) and screen height (for y)
- <halign> is the horizontal alignment of the text. 0 is left, 1 is right, 2 is center.
- <content> is the actual message, defined as a script.
That’s it for now. On the next post, we’ll talk about defining cards and decks. Almost ready for a full tutorial!