Skip to main content

T.I.M.E Stories Deck Generation Tools

pypi python MIT pre-commit black isort flake8

Overview

These tools were developed for use with the Heresy series of T.I.M.E Stories scenarios. For more details on the scenarios and how to obtain them, see Heresy.

The source code of this package is being made available under an MIT open source license. See LICENSE for additional Copyright information. See the file deck_format.rst for a more detailed description of the deck XML schema and renderable entities details.

What can they do?

The Heresy, Python-based toolset is capable of laying out and rendering cards in various forms. It is capable of generating individual PNG files for the top and bottom of each card in the deck as well as Letter and A4 format PDF files of the whole deck and the composite PNG file deck images used by Tabletop Simulator from the same XML source. The tool has the ability to generate cards padded out with the bleeding region needed for printing services like makeplayingcards.com.

How do they work?

The tools work on a ‘deck’ file, an XML formatted description of a T.I.M.E Stories deck. A deck contains lists of cards (e.g. Items, plans, characters, etc). Each card contains a set of text or image blocks that can be sized, rotated and placed on the card. Individual items have the concept of ‘depth’ which controls the compositing order of the various card elements. Finally, every type of card has a “default” card that it can inherit from as base layer. This makes it very easy to do things like add the item number to all item cards by adding it to the default card with a depth that ensures it is visible over (or under) other content.

The deck XML schema describes text styles and images as “assets” that can be referenced by name on the cards. One can even refer to subsections of a source image file as an image, making it very simple to crop out portions of a larger image (or a single image of a location into cards) and use them in additional places. We often import the Space Cowboys’ SDK at the start of a new scenario for consistency with other decks.

At the heart of the deck is the representation of a card face. Every card has a top and a bottom face with a different collection of renderable items. The final rendered card is a composite of the current card items and any items from the default card for the current card type. The items from the card and the default card are merged and sorted by depth (layers) that determine the order of the item compositing. There are rectangle, image and text items. The text item plays a key role as much of the story is told through these items. The text item allows for the application of styles to sections of text that are common over all cards (e.g. all item references should be bold and green). Text can include macros that substitute for actual card names, numbers, letters, etc. These are computed when the card is rendered and help make sure that moving things around leaves most links intact. Image objects can even be embedded (inline) into the text of a text item. In short enough functionality to cover the needs of the Heresy story.

Quick Example

Suppose one has a file named hersey.deck and Python has been installed in C:Python310. The tools can be installed by building them from source or installing the module via pip:

C:\Python310\python.exe -m pip install heresycardbuilder

One can build output imagery types using the command line:

C:\Python310\Scripts\build_deck --pdf --tabletop heresy.deck

It will create a directory generated_cards in the same directory as hersey.deck and place all of the generated output products into the target directory.

The complete command line to the tool looks like:

usage: build_deck [-h] [--version] [--outdir [OUTDIR]] [--pad_width [PAD_WIDTH]] [--default_deck [dirname ...]] [--card [card_number]] [--mpc] [--pdf] [--tabletop] [--verbose] [--logfile LOGFILE] cardfile

Generate T.I.M.E Stories cards from art assets.

positional arguments:
  cardfile              The name of a saved project.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --outdir [OUTDIR]     The name of a saved project.
  --pad_width [PAD_WIDTH]
                        Extra border padding for printing.
  --default_deck [dirname ...]
                        Create new deck from images in directories
  --card [card_number]  Render a single card
  --mpc                 Set up for printing with makeplayingcards.com (same as --pad_width 36)
  --pdf                 Generate pdf files from the generated cards
  --tabletop            Generate Tabletop Simulator deck images from generated cards
  --verbose             Enable verbose mode
  --logfile LOGFILE     Save console output to the specified file

The most useful options are --outdir, --card, --pdf and --tabletop.

Notes

The card builder uses the Qt rendering engine to generate card images. If you are using custom TrueType typefaces in your deck, they need to be installed such that the version of Qt used by your Python interpreter can access the typeface.

The project is dependent on Python 3.10 and PySide6. It was developed in PyCharm.

Developers

Building the package is pretty straightforward. The use of a virtual environment is strongly recommended.

git clone https://github.com/randall-frank/heresy-card-builder.git
cd heresy-card-builder
pip install virtualenv
python -m virtualenv venv
.\venv\Scripts\activate.ps1   # for Windows PowerShell, different for other shells
pip install .[dev]

Build

To build and install heresycardbuilder tools, run these commands:

python -m build
python -m pip uninstall heresycardbuilder -y
python -m pip install .\dist\heresycardbuilder-0.9.0-py3-none-any.whl
build_deck --help

Pre-commit

pre-commit is used in this project to enforce code styling and other features. Code must pass the pre-commit check before it can be committed to the repo.

To install pre-commit into your git hooks, run this command:

pre-commit install

pre-commit then runs on every commit. Each time you clone a project, installing pre-commit should always be the first action that you take.

If you want to manually run all pre-commit hooks on a repository, run this command:

pre-commit run --all-files

flake8, isort, codespell and black will all be applied.

To run individual hooks, use this command, where <hook_id> is obtained from from the .pre-commit-config.yaml file:

pre-commit run <hook_id>

The first time pre-commit runs on a file, it automatically downloads, installs, and runs the hook.

Testing

Basic unit tests are implemented using pytest. To run the tests:

pytest

TODO

  • New cards/copy/paste

  • Issues with deleted assets?

  • Reordering computation with no or higher-level parent (no ‘obj’ on the parent)


Copyright (C) 2017-2025 Randall Frank

Metadata

Release files for heresycardbuilder 0.9.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for heresycardbuilder 0.9.1
File Size Uploaded Provenance Actions
heresycardbuilder-0.9.1.tar.gz 3.7 MB Without provenance Details for heresycardbuilder-0.9.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for heresycardbuilder 0.9.1
File Interpreter ABI Platform Actions
heresycardbuilder-0.9.1-py3-none-any.whl Python 3 none any Details for heresycardbuilder-0.9.1-py3-none-any.whl

Total release size: 7.5 MB

Release files / heresycardbuilder-0.9.1.tar.gz

Download URL heresycardbuilder-0.9.1.tar.gz
Size 3.7 MB
Tags Source
SHA-256 checksum
How to use checksums
c59a218ba10bed3abfdc5f02442ecc52648ec83db58d65b6fdcb12fac49ec2dd
BLAKE2b-256 checksum
How to use checksums
d2dbac6f76775b62abc83f8ca17e798636499bcb8d50a622ef27a9357dd367e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.0.1 CPython/3.10.11

Release files / heresycardbuilder-0.9.1-py3-none-any.whl

Download URL heresycardbuilder-0.9.1-py3-none-any.whl
Size 3.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
5600d2b7be233165f8b91833eff80f1fb1d1414d54e72c561ca4f426ac8605de
BLAKE2b-256 checksum
How to use checksums
c282232dc1b88c688361742f4702720da9039f1f25848c1fb419c52cf0bee7ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.0.1 CPython/3.10.11

Security for heresycardbuilder 0.9.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.9.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page