Custom Formats

Zwoptex 2.0 supports custom coordinates and manifest formats with either template tokens or using the Ruby programming language to allow full control over the output.


Location

All formatters are stored in one of two directories:

  • Coordinates formats in ~/Library/Application Support/Zwoptex/Coordinates Formats/
  • Manifest formats in ~/Library/Application Support/Zwoptex/Manifest Formats/

The files should be named using reverse style domains and have a file extension such as com.my-organization.zwoptex.formatter.json.


Metadata

Each custom format has a metadata section to help Zwoptex display it as an option in the targets panel as well as distinguish between Standard and Ruby templates. The metadata should be placed immediately at the top of the file as such:

---
name: <display name of the format>
extension: <file extension of the format>
type: <type of format, either token or ruby>
---

All three metadata entries are required and Zwoptex will not load custom formats missing any one of them.


Language Data Types

String

  • withoutExtension (String)
  • lowercased (String)
  • uppercased (String)
  • capitalized (String)
  • extension (String)

Renders as textual value

Number

Renders as numerical value

Boolean

Renders as true or false

File

  • path (String)
  • name (String)

Renders as name

Point

  • x (Number)
  • y (Number)

Renders as {x,y}

Size

  • width (Number)
  • height (Number)

Renders as {width,height}

Rect

  • x (Number)
  • y (Number)
  • origin (Point)
  • width (Number)
  • height (Number)
  • size (Size)
  • minX (Number)
  • maxX (Number)
  • minY (Number)
  • maxY (Number)

Renders as {{x, y}, {width, height}}

Metadata

  • name (String) - name of the document being published without file extension
  • version (String) - version of Zwoptex used

Target

  • name (String) - name of the target
  • scale (Number) - scale of the target from 0.0-1.0
  • scalePercentage (Number) - scale of the target from 0-100
  • scaleMode (String) - scale mode of the target

Sheet

  • coordinatesFile (File) - coordinates file
  • textureFile (File) - texture file
  • size (Size) - final pixel dimensions

Sprite

  • name (String) - name of the sprite
  • pathName (String) - path name of the sprite
  • sourceColorRect (Rect) - rectangle used to trim away transparent pixels
  • sourceSize (Size) - pixel size before trimming
  • offset (Point) - offset used to re-align image back in source size if trimmed
  • textureRect (Rect) - rectangle of pixels for the sprite in the sheet
  • trimmed (Boolean) - whether or not the sprite is trimmed
  • aliases (Array) - list of all sprites that are aliases of this sprite

Variables

Coordinates Formats

  • metadata (Metadata) - metadata
  • target (Target) - the target being published
  • sheet (Sheet) - the current sheet being published for the target
  • sprites (Array) - list of all non-aliased sprites for the sheet
  • spritesAndAliases (Array) - list of all sprites regardless of aliased or not for the sheet

Manifest Formats

  • metadata (Metadata) - metadata
  • target (Target) - the target being published
  • sheets (Array) - list of all the sheets published for the target

Token Type

Token type templates use the Liquid templating language with the above variables to generate a suitable output. The templating language is quite powerful but is logic-less and doesn’t allow math or other programmatic operations to be performed. You can use anything Liquid provides in these templates but below is the general guide that is most relevant to Zwoptex.

Tags

All control tags start with {% and end with %} while variable tags start with {{ and end with }}.

if

Executes a block of code only if a certain condition is met.

INPUT
<!-- If sprite.trimmed = true -->
{% if sprite.trimmed %}
  This sprite is trimmed!
{% endif %}
OUTPUT
This sprite is trimmed!

else

Adds more conditions within an if or unless block.

INPUT
<!-- If sprite.trimmed = false -->
{% if sprite.trimmed %}
  This sprite is trimmed!
{% else %}
  This sprite is not trimmed!
{% endif %}
OUTPUT
This sprite is not trimmed!

unless

Like if but executes a block of code only if the condition is not met.

INPUT
<!-- If sprite.trimmed = false -->
{% unless sprite.trimmed %}
  This sprite is not awesome.
{% endif %}
OUTPUT
This sprite is not awesome.

for

Executes a block of code repeatedly.

INPUT
{% for sprite in sprites %}
  {{ sprite.name }}
{% endfor %}
OUTPUT
Sprite 1
Sprite 2
Sprite 3
Loop Variables
  • loop.first (Boolean) - whether or not this is the first iteration
  • loop.last (Boolean) - whether or not this is the last iteration
  • loop.index (Boolean) - 0 based index
  • loop.index1 (Boolean) - 1 based index
  • loop.startIndex (Boolean) - 0 based start index
  • loop.startIndex1 (Boolean) - 1 based start index
  • loop.endIndex (Boolean) - 0 based end index
  • loop.endIndex1 (Boolean) - 1 based end index

Example

---
name: Zwoptex Token Custom
extension: txt
type: token
---
{% for sprite in spritesAndAliases %}

  This is sprite named "{{ sprite.name }}" at index {{ loop.index0 }}.

  {% if sprite.trimmed %}
    This sprite is trimmed!
  {% else %}
    This sprite is not trimmed!
  {% endif %}

 {% unless loop.last %}---{% endunless %}

{% endfor %}

Ruby Type

Ruby templates execute the template contents as a ruby script and capture the return value of the script. These scripts are executed using the system installed Ruby that comes with OS X and as such if you want to install and use any Gems you need to install them using the system gem command.

Ruby templates give you flexibility to perform math operations, or other programmable needs to generate your file output. Much like Ruby the last line should contain the output string value or you can explicitly return early with the output.

Example

---
name: Zwoptex Ruby Custom
extension: txt
type: ruby
---

lines = []
spritesAndAliases.each do |sprite|
  lines << sprite.name  
end

lines.join("\n")