# Pakettic
Pakettic is a command-line tool for minifying and compressing
[TIC-80](http://tic80.com/) fantasy console carts. The tool is written
in Python (3.9+) and used especially for
[sizecoding](http://www.sizecoding.org/wiki/TIC-80). It compresses
existing carts approximately ~1.2% better than best alternatives, and by
using its [magic comments](#magic-comments), pakettic might find code
that compresses even better.
## Installation
Installing with pip:
```bash
$ pip install pakettic
```
Installing the latest main branch from GitHub:
```bash
$ pip install git+https://github.com/vsariola/pakettic.git@main
```
Installing a checked out version of the repository:
```bash
$ pip install -e path/to/pakettic
```
Installing a checked out version of the repository using
[poetry](https://python-poetry.org/) for a nice virtual environment with
locked dependencies (run inside the pakettic folder):
```bash
$ poetry install
```
## Usage
To compress a cart, run:
```bash
$ pakettic path/to/cart.tic
```
If your PATH is not configured to include pip installed executables, you
can use
```bash
$ python -m pakettic path/to/cart.tic
```
If you installed using poetry into a virtual environment, you need to
prepend `poetry run` before every command e.g.
```bash
$ poetry run pakettic path/to/cart.tic
```
Pakettic supports both .tic and .lua carts. Multiple input files may be
defined. Input files are globbed, so `?`, `*`, and `**` work as
wildcards for a single character, multiple characters and a directory,
respectively.
For a full list of command line options, see:
```bash
$ pakettic --help
```
See also [tips for command line arguments](#tips-for-command-line-arguments)
Running all tests:
```bash
$ poetry run python -m unittest discover -s tests
```
## Features
Pakettic first parses the LUA-script to an abstract syntax tree, and
then uses a local optimization algorithm
([simulated annealing](https://en.wikipedia.org/wiki/Simulated_annealing),
[late acceptance hill climbing](https://arxiv.org/pdf/1806.09328.pdf) or
its variant diversified late acceptance search) to randomly mutate the
syntax tree & see if it compresses better. Implemented mutations
include:
- shortening variable names
- flipping comparisons `>`, `<`, `>=`, `<=`, `~=`, and `==`
- reordering arithmetic operators `+`, `-`, `*` and `/` and bit logic
operators `&`, `~` and `|`
- converting `a^2` into `a*a` and vice versa
- using either single or double quotes for all strings
- converting whole hexadecimals into decimals
- convert `for a,b,1 do` into `for a,b do` and vice versa
- reordering statements: statements that can be reordered are marked
with [magic comments](#magic-comments)
- alternative expressions: alternatives are marked with
[magic comments](#magic-comments)
- folding constant expressions
Internally, pakettic uses [zopfli](https://github.com/google/zopfli) for
the compression.
`load'<code>'` is parsed as `function(...)<code>end` so you can easily
recompress already compressed carts. Conversely, `function()<code>end`
or `function(...)<code>end` is replaced with `load'<code>'` during
compression.
Note that `function(...)<code>end` and `load'<code>'` are not 100%
semantically identical: the load version cannot access locals in the outer
scope. For example: `local x="hello" function f()print(x)end` works but
`local x="hello" f=load'print(x)'` does not. Since locals are rarely
used in size-coding, we default to using the load-trick, but you can
disable it with the command-line parameter `--no-load`.
However, pakettic does not convert functions with parameters. In
particular, pakettic does not automatically convert
`function SCN(x)<code>end` into `SCN=load'x=...<code>'`, because they
are not semantically identical: in the load version, `x` is now global
and thus could trash a global variable, unintentionally breaking the
cart. To make `SCN` compress nicely, you have to write it as
`function SCN(...)x=...<code>end`, taking responsibility for `x` not
overwriting anything important.
Unnecessary parentheses are removed from expressions so you do not have
to worry about those.
## Magic comments
### Reorderable statements
The algorithm will try to reorder statements between `--{` and `--}`.
For example:
```lua
--{
a="hello"
b="world"
--}
```
will try both `a="hello"b="world"` and `b="world"a="hello"` to see which
compresses better.
Notice that only complete statements can be reordered. Thus, this will
NOT work:
```lua
--{
for x=0,239 do
for y=0,135 do
--}
end
end
```
A good rule of thumb is that you should be able to replace `--{` and
`--}` with `do` and `end`, respectively, and still have valid code.
Statements between `--{!` and `--}` are not ordered, so you can make
blocks of statements that are kept in order within a pair of `--{` and
`--}` tags.
### Alternative expressions
There is a special `--|` operator that allows alternative expressions to
be tested, to see if they compress better. For example: `5--|4--|6`
means that the algorithm will try 4 and 6 in place of the 5. This will
naturally show up as a comment in LUA so you will have to continue the
expression on next line if this is in the middle of an expression. `--|`
has the lowest precedence, even lower than `^`, so put parentheses if
you want to try more complicated expressions e.g. `(x//256)--|(x>>8)`
### Debug code
Pakettic treats `--![` and `--!]` as multiline comment tags, while LUA
treats these as single line comments. Useful for including debug code in
the unpacked intro: the code will not be included in the packed cart.
## Tips for command line arguments
- If you have a CPU with many logical processors and want to max out your CPU
usage, you can increase the processing queue length with `-q`. You should
usually use `-q N` where N is the number of logical processors. Too high queue
length hurts the convergence rate. Defaults to 12.
- The Zopfli compression level can be set with `-z<level>`, with level
ranging from 0 to 5. When developing, start with `-z0` for fast
optimization, and only increase when necessary e.g. when you are just
a few bytes over the limit. The default Zopfli-level is 0.
- The algorithm uses a pseudorandom generator. Sometimes using a
different seed finds a few byte better or worse solution. Use command
line argument `--seed` to try different seeds.
- Similarly, different optimization heuristics produce slightly
different results. Try different heuristics e.g. with `-alahc`,
`-adlas` or `-aanneal`.
- To avoid re-optimizing all the expressions every time, do a long optimization
run, study the results and change your expressions to the forms that pack
well. Set the number of steps with `-s`; `-s0` iterates forever. Intermediate
results are saved. Use command-line argument `-p` to always print a reasonably
readable version of the best solution when one is found.
- By default, pakettic only includes CODE and DEFAULT chunks. DEFAULT
indicates that before loading the cart, TIC-80 loads the default cart,
setting default palette, waveforms etc. If you don't need the default
values (e.g. you set the palette yourself), save one byte by only
including CODE chunk in the cart: `-ccode`
- Working on a tweet-cart? Use `-flua` to output LUA carts, which are
uncompressed. The optimization algorithm then just optimizes the uncompressed
size of the code.
- If the packed cart is missing sprites, music, map etc., try adding
`-call` (or something more specific) to include necessary chunks.
- Do you want to use the TIC-80 sprites or the tracker, but don't like the fact
that the data chunks are uncompressed? Is your code longer than 65536
characters? Use `-fpng` to output "fake" PNG-like carts, which TIC-80 detects
as PNGs based on their headers and loads the cart from a `caRt` chunk, which
contains a TIC-80 cart, but this time the entire cart is compressed. ~ 20
bytes of additional headers are needed to fool TIC-80, so this is not
recommended for very tiny intros. You need to specify which data chunks should
be kept. For example, `-fpng -cCODE,MUSIC,PATTERNS,WAVEFORM,SAMPLES,DEFAULT`
would include the necessary chunks for the music. PNG-like carts require
TIC-80 v1.1.2729 or newer.
- Alternative way to use data chunks is to use `-d` to have pakettic
automatically convert data chunks in bank 0 into hexadecimal strings in the
code, along with a small stub placed at the beginning of the code that
interprets the string and loads the data at correct address. This breaks
`sync` from bank 0, so use with care in multibank carts.
## Known issues
- At the moment, all the branches of swappable operators are assumed to
be without side effects. If they have side-effects, the swapping might
inadvertedly swap the execution order of the two branches.
- The parser can crash with large carts. Carts in the size coding range
(few thousand characters) do not seem to cause problems, but crashes
have been observed parsing carts with tens of thousands of code
characters. This may be related to how the pyparsing grammar is
defined, which could result in highly recursive parsing and eventually
stack overflows.
## Credits
Code contributors: [Veikko Sariola/pestis](https://github.com/vsariola), [wojciech-graj](https://github.com/wojciech-graj),
[koorogi](https://github.com/koorogi), [dezgeg](https://github.com/dezgeg)
Test corpus contributors: [psenough](corpus/psenough/), [ilmenit](corpus/ilmenit/),
[gigabates](corpus/gigabates/), [gasman](corpus/gasman/), [pellicus](corpus/pellicus/),
[luchak](corpus/psenough/fabracid.lua).
## License
[MIT](https://choosealicense.com/licenses/mit/)
The test corpus carts have their own licenses, see the license files in
the subdirectories of the [corpus](corpus/) directory.
Raw data
{
"_id": null,
"home_page": "https://github.com/vsariola/pakettic",
"name": "pakettic",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "TIC-80, Fantasy Console, Compression, LUA",
"author": "Veikko Sariola",
"author_email": "5684185+vsariola@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/e3/cf/e1f5f60da2662aab54eaa5461ccc4e509271aadf7c988b9d68325679db45/pakettic-1.4.0.tar.gz",
"platform": null,
"description": "# Pakettic\n\nPakettic is a command-line tool for minifying and compressing\n[TIC-80](http://tic80.com/) fantasy console carts. The tool is written\nin Python (3.9+) and used especially for\n[sizecoding](http://www.sizecoding.org/wiki/TIC-80). It compresses\nexisting carts approximately ~1.2% better than best alternatives, and by\nusing its [magic comments](#magic-comments), pakettic might find code\nthat compresses even better.\n\n## Installation\n\nInstalling with pip:\n\n```bash\n$ pip install pakettic\n```\n\nInstalling the latest main branch from GitHub:\n\n```bash\n$ pip install git+https://github.com/vsariola/pakettic.git@main\n```\n\nInstalling a checked out version of the repository:\n\n```bash\n$ pip install -e path/to/pakettic\n```\n\nInstalling a checked out version of the repository using\n[poetry](https://python-poetry.org/) for a nice virtual environment with\nlocked dependencies (run inside the pakettic folder):\n\n```bash\n$ poetry install\n```\n\n## Usage\n\nTo compress a cart, run:\n\n```bash\n$ pakettic path/to/cart.tic\n```\n\nIf your PATH is not configured to include pip installed executables, you\ncan use\n\n```bash\n$ python -m pakettic path/to/cart.tic\n```\n\nIf you installed using poetry into a virtual environment, you need to\nprepend `poetry run` before every command e.g.\n\n```bash\n$ poetry run pakettic path/to/cart.tic\n```\n\nPakettic supports both .tic and .lua carts. Multiple input files may be\ndefined. Input files are globbed, so `?`, `*`, and `**` work as\nwildcards for a single character, multiple characters and a directory,\nrespectively.\n\nFor a full list of command line options, see:\n\n```bash\n$ pakettic --help\n```\n\nSee also [tips for command line arguments](#tips-for-command-line-arguments)\n\nRunning all tests:\n\n```bash\n$ poetry run python -m unittest discover -s tests\n```\n\n## Features\n\nPakettic first parses the LUA-script to an abstract syntax tree, and\nthen uses a local optimization algorithm\n([simulated annealing](https://en.wikipedia.org/wiki/Simulated_annealing),\n[late acceptance hill climbing](https://arxiv.org/pdf/1806.09328.pdf) or\nits variant diversified late acceptance search) to randomly mutate the\nsyntax tree & see if it compresses better. Implemented mutations\ninclude:\n - shortening variable names\n - flipping comparisons `>`, `<`, `>=`, `<=`, `~=`, and `==`\n - reordering arithmetic operators `+`, `-`, `*` and `/` and bit logic\n operators `&`, `~` and `|`\n - converting `a^2` into `a*a` and vice versa\n - using either single or double quotes for all strings\n - converting whole hexadecimals into decimals\n - convert `for a,b,1 do` into `for a,b do` and vice versa\n - reordering statements: statements that can be reordered are marked\n with [magic comments](#magic-comments)\n - alternative expressions: alternatives are marked with\n [magic comments](#magic-comments)\n - folding constant expressions\n\nInternally, pakettic uses [zopfli](https://github.com/google/zopfli) for\nthe compression.\n\n`load'<code>'` is parsed as `function(...)<code>end` so you can easily\nrecompress already compressed carts. Conversely, `function()<code>end`\nor `function(...)<code>end` is replaced with `load'<code>'` during\ncompression.\n\nNote that `function(...)<code>end` and `load'<code>'` are not 100%\nsemantically identical: the load version cannot access locals in the outer\nscope. For example: `local x=\"hello\" function f()print(x)end` works but\n`local x=\"hello\" f=load'print(x)'` does not. Since locals are rarely\nused in size-coding, we default to using the load-trick, but you can\ndisable it with the command-line parameter `--no-load`.\n\nHowever, pakettic does not convert functions with parameters. In\nparticular, pakettic does not automatically convert\n`function SCN(x)<code>end` into `SCN=load'x=...<code>'`, because they\nare not semantically identical: in the load version, `x` is now global\nand thus could trash a global variable, unintentionally breaking the\ncart. To make `SCN` compress nicely, you have to write it as\n`function SCN(...)x=...<code>end`, taking responsibility for `x` not\noverwriting anything important.\n\nUnnecessary parentheses are removed from expressions so you do not have\nto worry about those.\n\n## Magic comments\n\n### Reorderable statements\n\nThe algorithm will try to reorder statements between `--{` and `--}`.\nFor example:\n\n```lua\n --{\n a=\"hello\"\n b=\"world\"\n --}\n```\n\nwill try both `a=\"hello\"b=\"world\"` and `b=\"world\"a=\"hello\"` to see which\ncompresses better.\n\nNotice that only complete statements can be reordered. Thus, this will\nNOT work:\n\n```lua\n --{\n for x=0,239 do\n for y=0,135 do\n --}\n end\n end\n```\n\nA good rule of thumb is that you should be able to replace `--{` and\n`--}` with `do` and `end`, respectively, and still have valid code.\n\nStatements between `--{!` and `--}` are not ordered, so you can make\nblocks of statements that are kept in order within a pair of `--{` and\n`--}` tags.\n\n### Alternative expressions\n\nThere is a special `--|` operator that allows alternative expressions to\nbe tested, to see if they compress better. For example: `5--|4--|6`\nmeans that the algorithm will try 4 and 6 in place of the 5. This will\nnaturally show up as a comment in LUA so you will have to continue the\nexpression on next line if this is in the middle of an expression. `--|`\nhas the lowest precedence, even lower than `^`, so put parentheses if\nyou want to try more complicated expressions e.g. `(x//256)--|(x>>8)`\n\n### Debug code\n\nPakettic treats `--![` and `--!]` as multiline comment tags, while LUA\ntreats these as single line comments. Useful for including debug code in\nthe unpacked intro: the code will not be included in the packed cart.\n\n## Tips for command line arguments\n\n- If you have a CPU with many logical processors and want to max out your CPU\n usage, you can increase the processing queue length with `-q`. You should\n usually use `-q N` where N is the number of logical processors. Too high queue\n length hurts the convergence rate. Defaults to 12.\n- The Zopfli compression level can be set with `-z<level>`, with level\n ranging from 0 to 5. When developing, start with `-z0` for fast\n optimization, and only increase when necessary e.g. when you are just\n a few bytes over the limit. The default Zopfli-level is 0.\n- The algorithm uses a pseudorandom generator. Sometimes using a\n different seed finds a few byte better or worse solution. Use command\n line argument `--seed` to try different seeds.\n- Similarly, different optimization heuristics produce slightly\n different results. Try different heuristics e.g. with `-alahc`,\n `-adlas` or `-aanneal`.\n- To avoid re-optimizing all the expressions every time, do a long optimization\n run, study the results and change your expressions to the forms that pack\n well. Set the number of steps with `-s`; `-s0` iterates forever. Intermediate\n results are saved. Use command-line argument `-p` to always print a reasonably\n readable version of the best solution when one is found.\n- By default, pakettic only includes CODE and DEFAULT chunks. DEFAULT\n indicates that before loading the cart, TIC-80 loads the default cart,\n setting default palette, waveforms etc. If you don't need the default\n values (e.g. you set the palette yourself), save one byte by only\n including CODE chunk in the cart: `-ccode`\n- Working on a tweet-cart? Use `-flua` to output LUA carts, which are\n uncompressed. The optimization algorithm then just optimizes the uncompressed\n size of the code.\n- If the packed cart is missing sprites, music, map etc., try adding\n `-call` (or something more specific) to include necessary chunks.\n- Do you want to use the TIC-80 sprites or the tracker, but don't like the fact\n that the data chunks are uncompressed? Is your code longer than 65536\n characters? Use `-fpng` to output \"fake\" PNG-like carts, which TIC-80 detects\n as PNGs based on their headers and loads the cart from a `caRt` chunk, which\n contains a TIC-80 cart, but this time the entire cart is compressed. ~ 20\n bytes of additional headers are needed to fool TIC-80, so this is not\n recommended for very tiny intros. You need to specify which data chunks should\n be kept. For example, `-fpng -cCODE,MUSIC,PATTERNS,WAVEFORM,SAMPLES,DEFAULT`\n would include the necessary chunks for the music. PNG-like carts require\n TIC-80 v1.1.2729 or newer.\n- Alternative way to use data chunks is to use `-d` to have pakettic\n automatically convert data chunks in bank 0 into hexadecimal strings in the\n code, along with a small stub placed at the beginning of the code that\n interprets the string and loads the data at correct address. This breaks\n `sync` from bank 0, so use with care in multibank carts.\n\n## Known issues\n\n- At the moment, all the branches of swappable operators are assumed to\n be without side effects. If they have side-effects, the swapping might\n inadvertedly swap the execution order of the two branches.\n- The parser can crash with large carts. Carts in the size coding range\n (few thousand characters) do not seem to cause problems, but crashes\n have been observed parsing carts with tens of thousands of code\n characters. This may be related to how the pyparsing grammar is\n defined, which could result in highly recursive parsing and eventually\n stack overflows.\n\n## Credits\n\nCode contributors: [Veikko Sariola/pestis](https://github.com/vsariola), [wojciech-graj](https://github.com/wojciech-graj),\n[koorogi](https://github.com/koorogi), [dezgeg](https://github.com/dezgeg)\n\nTest corpus contributors: [psenough](corpus/psenough/), [ilmenit](corpus/ilmenit/),\n[gigabates](corpus/gigabates/), [gasman](corpus/gasman/), [pellicus](corpus/pellicus/),\n[luchak](corpus/psenough/fabracid.lua).\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n\nThe test corpus carts have their own licenses, see the license files in\nthe subdirectories of the [corpus](corpus/) directory.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for minifying and compressing TIC-80 fantasy console carts",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/vsariola/pakettic",
"Repository": "https://github.com/vsariola/pakettic"
},
"split_keywords": [
"tic-80",
" fantasy console",
" compression",
" lua"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8bc7517111f1ffb5af5144189bceffec48d53098e69880a70e00139484a63d78",
"md5": "c2ef1d5162168069cacafe645420c1ae",
"sha256": "f8f8cc443a561bfc7a01b4501644f1a23ecf9c2faae07d260d1ce074b328057d"
},
"downloads": -1,
"filename": "pakettic-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2ef1d5162168069cacafe645420c1ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 32474,
"upload_time": "2024-05-05T13:55:37",
"upload_time_iso_8601": "2024-05-05T13:55:37.707913Z",
"url": "https://files.pythonhosted.org/packages/8b/c7/517111f1ffb5af5144189bceffec48d53098e69880a70e00139484a63d78/pakettic-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3cfe1f5f60da2662aab54eaa5461ccc4e509271aadf7c988b9d68325679db45",
"md5": "0a1d25eecbad2b2e38ff562920c87e98",
"sha256": "bd1a9f56e522aff6e2d180616332583b7b83b832256485b1fea3d6eb8064de3b"
},
"downloads": -1,
"filename": "pakettic-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "0a1d25eecbad2b2e38ff562920c87e98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 31105,
"upload_time": "2024-05-05T13:55:40",
"upload_time_iso_8601": "2024-05-05T13:55:40.135460Z",
"url": "https://files.pythonhosted.org/packages/e3/cf/e1f5f60da2662aab54eaa5461ccc4e509271aadf7c988b9d68325679db45/pakettic-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 13:55:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vsariola",
"github_project": "pakettic",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pakettic"
}
JSON
