Skip to content

Latest commit

 

History

History
156 lines (123 loc) · 4.54 KB

file-processors.md

File metadata and controls

156 lines (123 loc) · 4.54 KB

Introduction to file processors

File processors are Lua functions that handle processing files at build-time with a specific extension. A file processor can simply copy a file or run external tools to process export a game-ready file.

Built-in file processors

Playbit includes out-of-the-box file processors for common file types:

Default/fallback

fileProcessors = {
  txt = build.defaultProcessor,
}

The default processor simply copies a file from the input path to the output path.

You can manually assign an extension to the default processor. However if a processor is not found, the build system will always fallback to this processor.

Skip File

fileProcessors = {
  cfg = {
    build.skipFile,
    {
      silent = true
    }
  }
}

The skip file processor can be used to skip files you don't want copied. Useful for project files that you want next to assets, but not something you want in your final build.

Optional parameters:

  • silent: If true, silences the log that is printed when a file is skipped. Defaults to false.

Aseprite

fileProcessors = {
  aseprite = {
    build.asepriteProcessor,
    {
      path = "C:/Program Files/Aseprite/Aseprite.exe",
      scale = 2,
      ignoredLayers = {
        "bg",
        "placeholder",
      },
    }
  }
}

Exports Aseprite files (.aseprite). Aseprite must be installed for this to work.

The aseprite executable must either be added to your system path or specified using the path variable below.

Optional parameters:

  • path: If set, this path is used to call Aseprite from the command-line instead of relying on your system path. Defaults to nil.
  • scale: Sets the scale to export the image at. Defaults to 1.0.
  • ignoredLayers: Hides layers by name from the exported image. Defaults to {}.

Caps fonts

fileProcessors = {
  fnt = build.fntProcessor,
}

Converts Caps fonts to BMFonts for use in Love2d.

Lua

fileProcessors = {
  lua = build.luaProcessor,
}

Uses LuaPreprocess to run your metaprogram and strip platform-dependent code.

Wave

fileProcessors = {
  wav = {
    build.waveProcessor,
    {
      path = "C:/ffmpeg/bin/ffmpeg.exe"
    }
  }
}

Converts .wav files to the Playdate-supported IMA ADPCM format. FFmpeg must be installed for this to work.

The FFmpeg executable must either be added to your system path or specified using the path variable below.

Optional parameters:

  • path: If set, this path is used to call FFmpeg from the command-line instead of relying on your system path. Defaults to nil.

PDXINFO

fileProcessors = {
  json = {
    build.pdxinfoProcessor,
    {
      incrementBuildNumber = true
    }
  }
}

Converts a JSON file to a PDXINFO file. Optionally auto increments the build number.

Optional parameters:

  • incrementBuildNumber: If true, the buildNumber will automatically be incremented before building. The source JSON file will also be updated, so that you can commit and track this change in source control. Defaults to false.

Custom

You can also create your own file processor, simply by defining a function in a build script.

local build = require("playbit.build")
local fs = require("playbit.tools.filesystem")

-- appends "hello world" to the end of text files
local function textProcessor(input, output, options)
  local inputFile = io.open(input, "rb")
  local contents = inputFile:read("a")
  inputFile:close()

  contents = contents.."\nhello world!"

  fs.createFolderIfNeeded(output)
  local outputFile = io.open(output, "w+b")
  outputFile:write(contents)
  outputFile:close()
end

build.build({ 
  fileProcessors = {
    txt = txtProcessor,
  },
})

File processor functions require three parameters:

  • input: a string of the absolute file path to the source file.
  • output: a string of the absolute file path to the destination file.
  • options: an object that contains key-value pairs that contains processor-specific settings.