Automating SVG images

In this post, we’ll show you how to generate card templates for sites like The Game Crafter using simple programming tools.

I use PHP in this demo, but the same principle can be applied in any scripting language (Python, Perl, or Bash would all work as well).

If you’d like to skip straight to the code, go to our svg-card-demo on GitHub.

Requirements

For the demo, you need:

The ability to run PHP 5+ on the command line.
The following files from our svg-card-demo
- generate.php
- list.csv
- template-card.svg

With these files, you can run the demo yourself. Here we will explain how they were built and why they work.

Understanding SVG

The beauty of SVG is that it is an open XML standard for vector art. More simply, it’s a text file that draws pictures.

Because of that fact, you can easily change the text (and colors) of an SVG file in ways that you can’t with a processed format like PNG or JPG.

To start, let’s look at a snippet of SVG code with the CSS removed for clarity:

<flowroot xml:space="preserve" id="flowRoot1809">
	<flowregion id="flowRegion1811">
		<rect id="rect1813" width="169.5" height="67.5" x="53.5" y="52.5" />
	</flowregion>
	<flowpara>
		Placeholder Text
	</flowpara>
</flowroot>

This text represents part of our sample SVG file:

Using a simple find-and-replace, we can change this part of the SVG at will:

	<flowpara>
		Placeholder Text
	</flowpara>

Understanding that concept, we created our template-card.svg file and saved it.

Preparing the card data

To change that text, we need some replacements. We setup our demo file with three specific items that we care about:

Placeholder text
Action text
Color

For the demo, we prepared a CSV from a spreadsheet. Using Google Sheets, we made the following:

Then exported the sheet as list.csv into the directory with our template file.

You can create this file with any spreadsheet program. Just be sure to save as CSV.

For our example, we just used the NATO phonetic alphabet. We also want a header row, which will be used by the script to create our data. The CSV looks like so:

Name,Text,Color
Alfa,The action text for Alfa tells what Alfa can do.,#ffff00
Bravo,The action text for Bravo tells what Bravo can do.,#ffff00
Charlie,The action text for Charlie tells what Charlie can do.,#ffff00
Delta,The action text for Delta tells what Delta can do.,#ffff00

How the script works

The generate.php script works in five parts:

Read the CSV file to an array of items.
Read the contents of the SVG template as a string.
Find and replace elements from the CSV into new copies of the SVG template.
Save the new SVG file.
Optionally export a PNG copy (if Inkscape is installed).

Our template SVG is deliberately simple. We simply search for three items to replace:

Placeholder Text
Action Text
#ffff00 (CSS for yellow)

Where #ffff00 is the yellow highlight color for our cards.

When processing, each row of the CSV is turned into an array of replacement data:

Name
Text
Color

The values from the CSV then are inserted into our template file. Here’s the code:

function replace_svg($svg, $row) {
  $find = [
    'Placeholder Text',
    'Action Text',
    '#ffff00',
  ];
  $replace = [
    $row['name'],
    $row['text'],
    $row['color'],
  ];
  $text = str_replace($find, $replace, $svg);
  return $text;
}

So in the case of our row, Lima, we insert the values:

Lima
The action text for Lima tells what Lima can do.
#ff0000 (CSS for red)

Then we create the new file card-lima.svg and save it to an svg directory.

To see what the exports look like, go to the demo png or the demo svg directories.

Note: the star behind the text is a lighter shade of red because SVGs support transparency, and that object is shaded at about 30% opacity.

Bonus: PNG export

If you’ve worked with printers like The Game Crafter, you know that they like 300 dpi files in PNG format for printing. With Inkscape, a free vector drawing program, we get that done for us as well.

function export_file($file, $location = 'svg', $target = 'png', $format = 'png', $dpi = 300) {
  $newfile = str_replace('.svg', '.png', $file);
  shell_exec("inkscape '$location/$file' --export-png='$target/$newfile' -d 300");
}

Inkscape comes with a command-line tool that can export a variety of file formats. Here we explicity ask for a 300 dpi PNG file using the -d switch.

Well, thanks for reading this little writeup. It’s saved us a ton of time (and some money) generating print-ready files.

If you like it, tweet about it @wingedfivegames.

Here’s an example of cards we created this way from our game The Geneva Accords:

Next time, we can take a look at more advanced formatting and layout options when generating your SVG files.