Skip to content

Instantly share code, notes, and snippets.

@iWas-Coder

iWas-Coder/skap-decl-file-fmt-spec.txt

Last active June 18, 2025 18:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save iWas-Coder/bc6269afb2b191d1e78faf6a7ec52c54 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save iWas-Coder/bc6269afb2b191d1e78faf6a7ec52c54 to your computer and use it in GitHub Desktop.
Download ZIP
SKAP Declarations File (DECL) Format Specification
Raw
skap-decl-file-fmt-spec.txt
SKAP Declarations File (DECL) Format Specification
==================================================
Copyright (C) Wasym A. Alonso. All Rights Reserved.
Version 1.0 - June 02, 2025
1. Introduction
This document specifies the "SKAP Declarations File (DECL)" text
format. It provides an ergonomic and convenient way to list and
declare asset files intended for inclusion in a "Sparky Asset Pack
(SKAP)". The format is human-readable, line-oriented, and designed for
ease of use in asset management workflows.
2. General Information
2.1. File Naming Convention
There is no mandated file naming convention or extension for DECL
files. Users are free to choose any filename and extension
(e.g. `.txt`, `.decl`, etc.) as suitable for their workflow.
2.2. Character Encoding
All DECL files must be encoded using UTF-8. A Byte Order Mark (BOM)
should not be present.
2.3. Line Endings
Lines are terminated by a line ending sequence. Parsers must correctly
handle both CRLF (Carriage Return Line Feed, `\r\n`) and LF (Line
Feed, `\n`) line endings by stripping both `\r` and `\n` characters
from the end of each line read.
3. Structure and Syntax
3.1. Overall File Structure
A DECL file consists of a sequence of asset groups. Each group begins
with a group header, followed by one or more asset path entries. Empty
lines and comment lines are ignored. The order of blocks and entries
within blocks is preserved.
3.2. Basic Building Blocks
3.2.1. Group Header
A group header defines a base directory (`<PATH>`) and the type
(`<TYPE>`) for the assets listed within that group.
Its syntax is: `["<PATH>" as <TYPE>]`. It has the following
requirements and constraints:
- The `<PATH>` field must be a valid relative or absolute path.
- The `<PATH>` field must use forward slashes (`/`) as path
separators, regardless of the operating system.
- The `<PATH>` field must end with a forward slash (`/`), denoting
path termination.
- The `<PATH>` field must not be empty.
- The maximum length of the `<PATH>` field must be defined and
configurable in the parser.
- The `<TYPE>` field must be one of the pre-defined allowed types by
the parser implementation itself. Parsers must provide specific
error messages for unrecognized types, and also hints for common
typos (e.g. "image" instead of "images").
- The maximum length of the `<TYPE>` field must be defined and
configurable in the parser.
- No extra whitespaces are permitted within the header structure.
- If two group headers appear consecutively without an asset path
entry in between, a syntax error must be reported.
3.2.2. Asset Path Entries
An asset path entry specifies a single asset file relative to the
current group's `<PATH>`. Its maximum length must be defined and
configurable in the parser.
All assets within a group share the same `<TYPE>`. It's possible for
multiple groups to use the same `<TYPE>`, allowing assets from
different physical locations to be categorized under one logical type
in the SKAP.
3.2.3. Comments
Lines starting with exactly two forward slashes (`//`) are considered
comments and must be ignored by parsers. They can appear anywhere in
the file, including on their own line, before a group header, or
within an asset group.
3.2.4. Empty Lines
Lines containing only whitespace or no characters before the line
ending are considered empty and must be ignored.
4. Examples
4.1. Valid Example File
```
["assets/textures/" as images]
wood.png
stone.png
tile.png
grass.png
// This group is commented out and will be ignored
// ["assets/music/" as music]
// menu.ogg
// game.ogg
["assets/images/" as images]
logo.png
```
4.2. Invalid Example File
```
my_asset.txt // ERROR: Asset without a preceding group declaration
["assets/textures" as images] // ERROR: Base directory must end with '/'
["assets/models/" as models] // ERROR: Consecutive group declaration
model.obj
```
;; Local Variables:
;; mode: text
;; coding: utf-8
;; fill-column: 80
;; End:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment