Command Line

Zwoptex command line allows in depth integration into other build tools such as Xcode without having to use the app's graphical interface.

Usage: -c [JSON configuration file]

Configuration File

The configuration file contains all of the settings, targets and resource paths used by the command line tool. To assist in creating these configuration files you can with any Zwoptex document go to File -> Export Command Line Config… which will export the current document's configuration to a suitable configuration file.

Environment Variables

Environment variables are a vital part of command line integration and the configuration file fully supports environment variable replacement using a $(ENV_VARIABLE_NAME) notation. The following environment variables are provided by Zwoptex for use:

  • $(WORKING_DIR) - a file path to the directory the command line tool was executed from
  • $(CONFIG_FILE_DIR) - a file path to the directory containing the configuration file
  • $(DOCUMENT) - the config file name without extension
  • $(TARGET) - the current target name
  • $(SHEET) - the current sheet number padded to 4 digits



  • settings (required, Dictionary) - settings entry
    • sheet-width (required, Number) - maximum sheet width (may end up larger if using next power of two sizing mode)
    • sheet-height (required, Number) - maximum sheet height (may end larger if using next power of two sizing mode)
    • sheet-size-mode (optional, String, defaults to any) - size mode to use once layout is finished
      • any - reduces size down to fit the layout size
      • next_power_of_two - each dimension enlarged to next power of two
      • squared_next_power_of_two - each dimension enlarged to next of power two then ensures both width and height are identical
      • fixed - keeps size set to sheet width and height
    • layout-mode (optional, String, defaults to complex) - layout algorithm to use
      • complex - uses hueristics to best pack the sprites in spacing
      • basic - uses name based sorting to pack sprites evenly
    • layout-padding (optional, Number, defaults to 2) - amount of padding to add on the inside edges of sheets
    • layout-spacing (optional, Number, defaults to 2) - amount of padding to add on the outside edges of sprites
    • sprite-extruding (optional, Number, defaults to 0) - amount of extruding to add on the outside edges of sprites
    • sprite-padding (optional, Number, defaults to 0) - amount of padding to add on the inside edges of sprites
    • sprite-aliasing (optional, Boolean, defaults to true) - whether or not to enable aliasing which matches identical sprites to the same spot in the texture sheet(s)
    • sprite-trimming (optional, Boolean, defaults to true) - whether or not to enable trimming which trims transparent areas away from the edges of sprites


  • targets (optional, Dictiionary) - target entries, keyed by target name
    • scale (optional, Number, defaults to 1.0) - scaling to apply for single target
    • scale-mode (optional, String, defaults to smooth) - scaling algorithm to use
      • smooth - uses trilinear which smooths out artifacts
      • nearest_neightbor - uses nearest neighbor which keeps hard edged artifacts
    • coordinates - (optional, Dictionary) - coordinates settings
      • file-path (required, String) - coordinates file path
      • format (required, String) - coordinates file format identifier
    • texture - (optional, Dictionary) - texture settings
      • file-path (required, String) - texture file path
      • format (required, String) - texture file format identifier
        • com.zwopple.texture.png - png image
        • com.zwopple.texture.rgba - raw RGBA pixels
        • com.zwopple.texture.pvr_rgba_8888 - PowerVR RGBA 8888
        • com.zwopple.texture.pvr_bgra_8888 - PowerVR BGRA 8888
        • com.zwopple.texture.pvr_rgba_4444 - PowerVR RGBA 4444
        • com.zwopple.texture.pvr_rgba_5551 - PowerVR RGBA 5551
        • com.zwopple.texture.pvr_rgb_888 - PowerVR RGB 8888
        • com.zwopple.texture.pvr_rgb_565 - PowerVR RGB 565
        • com.zwopple.texture.pvr_a_8 - PowerVR A 8
        • com.zwopple.texture.pvr_pvrtc_2bpp - PowerVR PVRTC 2 BPP
        • com.zwopple.texture.pvr_pvrtc_4bpp - PowerVR PVRTC 4 BPP
        • com.zwopple.texture.pvr_pvrtc_ii_2bpp - PowerVR PVRTC II 2 BPP
        • com.zwopple.texture.pvr_pvrtc_ii_4bpp - PowerVR PVRTC II 4 BPP
      • color-profile (optional, String, defaults to com.zwopple.texture.colorprofile.none) - texture file color profile format identifier
        • com.zwopple.texture.colorprofile.none - include no color profile
        • com.zwopple.texture.colorprofile.srgb - include sRGB color profile
        • com.zwopple.texture.colorprofile.generic - include Generic RGB color profile
      • compression (optional, String, defaults to com.zwopple.texture.compression.none) - texture file compression format identifier
        • com.zwopple.texture.compression.none - do not compress file
        • com.zwopple.texture.compression.ccz - cocos2d zlib compression
      • dithering (optional, Boolean, defaults to true) - whether or not to apply dithering when reducing color depths
    • manifest - (optional, Dictionary) - manifest settings
      • file-path (required, String) - manifest file path
      • format (required, String) - manifest file format identifier


  • resources (optional, Array) - array of file paths for resources to generate sprite sheet from. Can be folders or individual files.

Example Configuration

This example would use pretty standard settings and export two targets one at full resolution as a @2x set and one at a half resolution as a normal set.

    "settings": {
        "sheet-width": 1024,
        "sheet-height": 1024,
        "sheet-size-mode": "any",
        "layout-mode": "complex",
        "layout-padding": 2,
        "layout-spacing": 2,
        "sprite-extruding": 0,
        "sprite-padding": 0,
        "sprite-aliasing": true,
        "sprite-trimming": true
    "targets": {
        "2x": {
            "scale": 1.0,
            "scale-mode": "smooth",
            "coordinates": {
                "file-path": "$(WORKING_DIR)/sprites-$(SHEET)@2x.plist",
                "format": "com.zwopple.zwoptex.coordinates.cocos2d"
            "texture": {
                "file-path": "$(WORKING_DIR)/sprites-$(SHEET)@2x.png",
                "format": "com.zwopple.zwoptex.texture.png",
                "color-profile": "com.zwopple.zwoptex.texture.colorprofile.none",
                "compression": "com.zwopple.zwoptex.textrure.compression.none",
                "dithering": true
            "manifest": {
                "file-path": "$(WORKING_DIR)/[email protected]",
                "format": "com.zwopple.zwoptex.manifest.plist"
        "1x": {
            "scale": 0.5,
            "scale-mode": "smooth",
            "coordinates": {
                "file-path": "$(WORKING_DIR)/sprites-$(SHEET).plist",
                "format": "com.zwopple.zwoptex.coordinates.cocos2d"
            "texture": {
                "file-path": "$(WORKING_DIR)/sprites-$(SHEET).png",
                "format": "com.zwopple.zwoptex.texture.png",
                "color-profile": "com.zwopple.zwoptex.texture.colorprofile.none",
                "compression": "com.zwopple.zwoptex.textrure.compression.none",
                "dithering": true
            "manifest": {
                "file-path": "$(WORKING_DIR)/sprites.plist",
                "format": "com.zwopple.zwoptex.manifest.plist"
    "resources": [