# Board Game Factory
#### Contributors are welcome here! :) See the last section of this Readme
This is a tool for rapid creation of paper prototypes of your cards, tiles,
tokens and sheets.
Here are samples of what I've made with Board Game Factory:
https://imgur.com/a/TS779gR
I've developed it personally to satisfy my need for a solid prototyping
engine for board games (couldn't find anything that did what I wanted, so I
made it myself). It can be used just as a simple rendering library for python,
to make whatever you want.
It uses vector graphics for rendering (cairo & pango libraries on the backend).
**DISCLAIMER:** The framework is still under development, it is quite feature
complete,
I used it to make and print thousands of cards and other board game assets
already,
but from QoL perspective, there are many things that could be improved. So
before we
reach version 1.0, expect updates to possibly present breaking changes. We will
keep it to absolute minimum and do it with consideration, but we want to keep
this freedom. So
always update
with caution, preferably creating a separate venv.
## Installation
### 1. Get Pango & Cairo
Pango & Cairo are the only prerequisites that cannot be installed with `pip`.
#### Windows
Install
this: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer
pango and cairo are included in this GTK+ for Windows Installer, all you need is
to install this on your system. (you can find alternatives too, if you look)
#### Linux
pango and cairo are most likely installed on your system already (they're at the
heart of GTK). You might need is to install `python-dev` and `libffi-dev` using
your OS's package manager.
(This was not tested, I'm referencing cairocffi and pangocffi docs, let me know
if it's inaccurate or doesn't work)
#### MacOS
```commandline
brew install pkg-config
brew install libffi
brew install pango
brew install glib
```
### 2. Install Board Game Factory
````commandline
pip install board-game-factory
````
### Having any issues?
`bgfactory` has the same prerequisites as `cairocffi` and `pangocffi`.
Take a look at documentation of pangocffi and cairocffi packages (these are the
python bindings into the binaries). Their installation instructions should work:
https://cairocffi.readthedocs.io/en/stable/overview.html#installing-cairocffi
https://pangocffi.readthedocs.io/en/latest/overview.html
If none of that works for you, create an Issue, describe your issues and all
that you've tried, and I can take a look at it.
# Getting Started
The following examples are the best documentation to date, contain a lot of
extra context. They also showcase many of the features and how to use them
together. So if you want to use this framework for yourself, read carefully
and use this as a reference.
all code presented below can be found in [examples/](examples/). They
purposefully don't contain a lot of code to be bite-sized and digestable.
## 01 - The Basics
[examples/01_basics.py](examples/01_basics.py)
Let's draw our first thing.
```python
from bgfactory import ff
component = ff.RoundedRectangle(0, 0, 300, 200, radius=60, stroke_width=15,
stroke_src=(0.2, 0.3, 0.7),
fill_src=ff.COLOR_WHITE)
component.image().show()
component.image().save('image.png')
```
The code above creates a rounded rectangle component, shows it on screen and
saves it to a png.
You should see this:
All drawing in the framework is done using components.
They represent everything elementary that's going to be drawn:
- a line or a rectangle
- piece of text
- ...
All components take `x, y` coordinates as their first arguments. What follows
is always definition of dimensions where suitable, `w, h` for most components
but e.g. circle is defined with `x, y, radius` instead of `x, y, w, h`.
The unit here is pixels. Even though on the backend vector graphics is used
with infinite resolution, you still need to ground the coordinate system in
something and pixels here are the most natural since they then correspond 1:1
with the dimensions of rendered images.
Every component extends `ff.Component` which also in turn allows to
use `.image()`
on every component. It returns a PIL.Image, which you
can easily manipulate further, most often with show or save.
This is very convenient, you have instant visual debugging for everything, even
your own components.
## 02 - Containers & Shapes
[examples/02_containers_and_shapes.py](examples/02_containers_and_shapes.py)
In order to make more complicated components you need some place to put them
together into and that's what containers are for.
Containers allow components to have descendants (we call them children here)
that render inside them.
Unlike for the `Component` base class, you will find yourself using the base
`Container` quite often, since it represents a rectangle container that has
no fill or border.
We use it here to showcase all the shapes and put them together in one picture.
In the beginning we add a white square to the middle for better visibility
no matter your background.
```python
from bgfactory import ff
# colors can be 3-tuple or 4-tuple of values between 0 and 1
COLOR1 = (232 / 255, 131 / 255, 7 / 255)
COLOR2 = (33 / 255, 196 / 255, 131 / 255)
COLOR3 = (32 / 255, 65 / 255, 212 / 255)
COLOR4_SEMITRANSPARENT = (32 / 255, 65 / 255, 212 / 255, 128 / 255)
COLOR5_SEMITRANSPARENT = (180 / 255, 60 / 255, 64 / 255, 128 / 255)
# for shapes: stroke = border, fill = inside
container = ff.Container(
0, 0, 400, 400,
children=[
ff.Rectangle(50, 50, 350, 350, fill_src=ff.COLOR_WHITE, stroke_width=0),
ff.Line(20, 380, 380, 20, stroke_width=5, stroke_src=COLOR3),
ff.Circle(140, 140, 80, stroke_width=5, stroke_src=COLOR1,
fill_src=COLOR2),
ff.RoundedRectangle(20, 20, 230, 230, stroke_width=5, stroke_src=COLOR1,
fill_src=ff.COLOR_TRANSPARENT),
]
)
container.add(
ff.RegularPolygon(130, 260, 40, 5, fill_src=COLOR4_SEMITRANSPARENT,
stroke_width=0),
ff.RegularPolygon(160, 220, 80, 6, fill_src=COLOR5_SEMITRANSPARENT,
stroke_width=0)
)
container.image().show()
```
Couple of things to note:
- notice 2 ways of adding components to a container, you can use either or both.
- all shapes extend `Container`, not `Component`, so you can easily put shapes
into other shapes.
- note the way the colors are defined, they have to be a 3-tuple or a 4-tuple of
floats between 0 and 1. The 4th channel represents transparency
- there is a good reason why the arguments are called stroke_src, fill_src
and not
stroke_color, fill_color. That's because the arguments are way more
flexible, imagine source
as being an image and the area to be filled simply a mask on this image.
For
a fixed color this corresponds to a filled rectangle, so you get the same
color everywhere. But you can for example also use any color gradient (
composed of arbitrary many colors) or even any image.
- So most of the time, src=color, but sometimes it allows you to do crazy
stuff
- notice that the order in which components are added they are also rendered
- `Container` cannot have any stroke or fill. If you need them, simply
use `Rectangle` instead, they are equivalent in every other way.
And finally, what you should see:
## 03 - Uniform Text and Alignment
Now let's see how do you render text. cairo is used for text rendering too,
however to get the render path, pango is used. General-purpose text rendering
is an incredibly complex problem with the amount of writing systems worldwide.
Since pango is at the core rendering engine of many Linux distributions,
pango can handle everything, any font, any locale, any writing system.
(In other words if some feature you would want is missing, write a feature
request, please :)
For text rendering, there are 2 components available at the moment:
`TextUniform` and `TextMarkup`. Their crucial difference is that `TextUniform`
imposes the same style on the whole text that's being rendered, whereas
`TextMarkup` allows you to mark the text with html tags to modify the style and
beyond that it has a feature of inlaying any Component directly into the text,
which is priceless when you want e.g. resource icons to be directly in text of
card descriptions.
Here we will take a look at the simpler one: `TextUniform`
In the following code, pay attention to a few things:
- we are importing pango as well as bgfactory
- pango is used for constants in `ff.FontDescription` (and nothing else from
user perspective)
- (these might get wrapped in the future so you don't have to deal with
this)
- the dimensions and coordinates are now parametric, we are taking advantage of
python being a
general purpose language to make adjusting our components as easy as possible.
The most efficient way to use this framework is to make everything parametric,
then you can change hundreds of assets significantly with 1 line change.
- you can define both stroke and fill on text. by default you get no stroke and
black fill, which is how text is rendered by default anywhere.
- we are defining text alignment (since the text component is given more space
than it can use, we have to tell it how to align itself, default is top-left)
- it can handle newlines with ease
[examples/03_text_and_alignment.py](examples/03_text_and_alignment.py)
```python
from bgfactory import ff
import pangocffi as pango
w = 500
h = 350
padding = 60
container = ff.RoundedRectangle(
0, 0, w, h, radius=60,
stroke_width=15, stroke_src=(0.2, 0.3, 0.7), fill_src=ff.COLOR_WHITE)
container.add(
ff.TextUniform(
padding, padding, w - 2 * padding, h - 2 * padding,
"Hello from Board Game Factory!\n\nHow are you doing today?",
fill_src=(0.2, 0.6, 0.9),
stroke_width=1,
stroke_src=ff.COLOR_BLACK,
font_description=ff.FontDescription(
family='Arial',
size=w * 0.06,
weight=pango.Weight.BOLD,
style=pango.Style.ITALIC,
),
halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_MIDDLE
)
)
container.image().show()
```
Notes:
- the names of the arguments of `FontDescription` always correspond 1:1 to a
pango namespace with relevant constants, so it shouldn't be too much of a
hassle using it
- you can also tweak character spacing as `stretch` in `ff.FontDescription` and
line spacing with `spacing` directly in `ff.TextUniform`.
- to install new fonts simply install them to your operating system
- if not sure where to get good fonts -> https://fonts.google.com/
What you should see:
## 04 - Layout Managers and Dynamic Size
[examples/04_layout_and_infer_size.py](examples/04_layout_and_infer_size.py)
Parametric layout is nice but still insufficient if you want to create asset
templates, rather than assets. And with a template, you don't necessarily know
the dimensions of your content.
Especially text will fluctuate in dimensions and often you don't want to take up
a lot of space, just in case there would be a lot of text.
What you would ideally want is some sort of dynamic layout which adjusts based
on the size of the content. You ultimately want the same layout options as in a
web-browser.
For this purpose, the base class `ff.LayoutManager` was created.
Layout manager is a part of every `ff.Container` (even when not seen by you).
When a container is being drawn, first its layout manager decides what is the
position and size of each child and only then are they drawn.
This allows not only for dynamic positioning but also dimensions.
The default layout manager that we were using so far, without knowing it,
is the `ff.AbsoluteLayout`. This is a very simple one, it just expects every
component to know its `x, y, w, h` beforehand and just places them accordingly.
For the dynamic behavior, currently 2 layout managers are implemented to
facilitate this:
- `ff.VerticalFlowLayout`
- `ff.HorizontalFlowLayout`
They are exactly the same, only one stacks items in the horizontal direction
and the other in the vertical.
Let's get to the example before explaining more:
```python
from bgfactory import ff
import pangocffi as pango
w = 400
h = 600
color = (0.2, 0.3, 0.7)
container = ff.RoundedRectangle(
0, 0, w, h, radius=30, stroke_width=5, stroke_src=color,
fill_src=ff.COLOR_WHITE,
padding=(30, 30, 30, 30),
layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER, valign=ff.VALIGN_TOP)
)
container.add(
ff.TextUniform(
0, 0, w * 0.8, ff.INFER,
"Card Title",
font_description=ff.FontDescription(
family='Arial',
size=w * 0.1,
weight=pango.Weight.BOLD,
style=pango.Style.NORMAL,
),
halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_MIDDLE
),
ff.TextUniform(
0, 0, w * 0.8, ff.INFER,
"This is a rather long card description. It contains multiple paragraphs that need to fit."
"\n\nWhen I wrote this, I wasn't quite sure how much space this will take."
"\n\nThat's when ff.INFER gets super handy!",
font_description=ff.FontDescription(
family='Arial',
size=w * 0.05,
weight=pango.Weight.NORMAL,
style=pango.Style.OBLIQUE,
),
halign=ff.HALIGN_LEFT,
valign=ff.VALIGN_MIDDLE,
margin=(0, h * 0.1, 0, 0)
),
ff.Container(
0, 0, '100%', ff.FILL,
layout=ff.HorizontalFlowLayout(halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_MIDDLE),
children=[
ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=1,
fill_src=ff.COLOR_TRANSPARENT, stroke_src=color),
ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=0,
fill_src=ff.COLOR_TRANSPARENT, stroke_src=color),
ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=1,
fill_src=ff.COLOR_TRANSPARENT, stroke_src=color)
]
)
)
container.image().show()
```
(see the render below)
- Notice we added `ff.VerticalFlowLayout` to the main container
and `ff.HorizontalFlowLayout` to the bottom one. So you can combine different
layout managers in hierarchies to get the desired layout
- All components that are children of a container
with `Horizontal/VerticalFlowLayout`
have their `x, y` coordinates ignored as the responsibility of positioning
is delegated to the given layout manager.
- Some width and heights have now weird values, let's go through them and their
intricacies (these are really key to understand, you will use them all the
time):
- `INFER` - used on the height of both of the text blocks. Both text fields
have fixed width, and then the pango backend is used to figure out how
tall will a given text be. This is then used during render.
- This can also be used on any container's width/height with these
dynamic flow layouts, because its children can tell it its size
- `'100%'` - means, to take up 100% of space of the parent container, can be
arbitrary float between 0 and 100, but is kept a string for clarity of
units, e.g. `'5%'` or `'3.1415%'`
- Cannot be used in conjunction with INFER of the same dimension on the
parent container. This creates a cyclic dependency. The validation
will crash
- `FILL` - fills the remaining area of the container
- for the dimension in flow direction, e.g. width
for `HorizontalFlowLayout` this can be used only on the last child to
fill the remaining width of the container. Analogously
for `height=FILL` and `VerticalFlowLayout`
- for the other dimension, it simply sets it to `'100%'`, filling the
whole available container space
- Each of them have `halign, valign` - they work as expected,
horizontal and vertical alignment of children in the layout
- Also notice `padding` and `margin`. These have the same definitions as in CSS.
- `padding` is like invisible internal border of a container. It pads the
children from all sides
- `margin` defines spacing between children of a container. Every child have
their own margins, however, just like with CSS, overlapping margins don't
add up. So if you define a margin of 10 pixels for every child, the space
between children will be 10px, not 20px. It always picks the bigger
margin. Note that this interaction doesn't happen with padding, padding
and margin stack as you would expect normally.
- they are defined with a 4-tuple, representing
order: `left, top, right, bottom`
- This is different from for example CSS, however it seemed more
intuitive
to me, as left and margins are typically the most important
Layout managers are the main source of flexibility and also complexity.
Use them wisely, they are definitely not needed every time. Very often the
default `AbsoluteLayout` in conjunction with parametric positioning is what
you want, only using flowy layout when you have text of significant variation
and/or need components to maintain spacing after dynamic text.
Also, there is one more layout option, check out `ff.Grid`, it doesn't adhere
to the `LayoutManager` pattern but does the same thing differently (see tests
for more detail before a tutorial on it is written)
Finally, the render result:
## 05 - Making your first template!
[examples/05_making_your_own_component.py](examples/05_making_your_own_component.py)
After you achieve the structure you wanted, it's time to package things up for
reuse. The intended usage pattern of board-game-factory is for you to create
your own component class, that will extend
typically `Container, RoudnedRectangle, Rectangle, ...` and you build the layout
in the constructor of such component. It also takes all necessary variables as
constructor params.
Packaging your components like this and always extending from `Component` makes
sure your components can always be defined just by the simple interface and
therefore can be used as a part of other components freely.
The following code does the same thing, but now the title and text are arguments
of our own `MyCard` component which we can render using `.image().show()` as
any component.
```python
from bgfactory import ff
import pangocffi as pango
CARD_WIDTH = 400
CARD_HEIGHT = 600
class MyCard(ff.RoundedRectangle):
def __init__(self, x, y, title, description, color=(0.2, 0.3, 0.7)):
pad = 25
super(MyCard, self).__init__(
x, y, CARD_WIDTH, CARD_HEIGHT, radius=30, stroke_width=5,
stroke_src=color, fill_src=ff.COLOR_WHITE,
padding=(pad, pad, pad, pad),
layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_TOP)
)
self.add(
ff.TextUniform(
0, 0, self.w * 0.8, ff.INFER,
title,
font_description=ff.FontDescription(
family='Arial',
size=self.w * 0.1,
weight=pango.Weight.BOLD,
style=pango.Style.NORMAL,
),
halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_MIDDLE,
)
)
self.add(
ff.TextUniform(
0, 0, self.w * 0.8, ff.INFER,
description,
font_description=ff.FontDescription(
family='Arial',
size=self.w * 0.045,
weight=pango.Weight.NORMAL,
style=pango.Style.OBLIQUE,
),
halign=ff.HALIGN_LEFT,
valign=ff.VALIGN_MIDDLE,
margin=(0, pad, 0, pad)
)
)
bottom_panel = ff.Container(
0, 0, '100%', ff.FILL,
layout=ff.HorizontalFlowLayout(halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_MIDDLE)
)
bottom_panel.add(
ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=1,
fill_src=ff.COLOR_TRANSPARENT,
stroke_src=color),
ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=0,
fill_src=ff.COLOR_TRANSPARENT,
stroke_src=color),
ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=1,
fill_src=ff.COLOR_TRANSPARENT,
stroke_src=color)
)
self.add(bottom_panel)
container = ff.Container(
0, 0, 2 * CARD_WIDTH, CARD_HEIGHT
)
container.add(
MyCard(
0, 0,
'Warlock',
'Warlocks are powerful users of magic. It is ancient and its origins are so old that they were long forgotten.'
'\n\nIt was once said, by a particular man, in a particular spot, that in order to find the origin warlock'
' magic, you have to go to the beginning of time, take a right turn, and continue until the edge of space.'
' Those who heard it were as confused as you are.\n\nDespite their power, Warlocks are typically cheerful '
'people, armed with an unexpected arsenal of dad jokes.'
),
MyCard(
CARD_WIDTH, 0,
'Rogue',
'Rogues are smart as they are sneaky. They can steal your wallet, your life but also, and not many '
'people know this, also your wife.\n\nThere have been accounts of rogues breaking into a house for a job '
'only to leave with the homeowner\'s wife instead of the loot, never to be found again (though probably'
' somewhere on the Canary Islands).',
color=(0.2, 0.7, 0.3)
),
)
container.image().show()
```
You can see that after defining our template with a class, we have abstracted
all of that dense text away and are left with just the things we want to tweak;
title, description and color.
And instantly we can render 2 different cards with the same layout just
with a few lines of code.
You would probably want to initialize these objects from a spreadsheet or a csv
file. I use google sheets myself to define all the dynamic content of all my
assets and load it in python using `gspread`. It works really well, I just
change some values in google sheets, press a button and instantly have a
brand new set of print sheets ready with the changes incorporated into all
affected assets.
Our result:
## 06 - How to scale it up and export for printing?
[examples/06_preparing_for_print.py](examples/06_preparing_for_print.py)
Now that we have our asset templates designed and populated with content,
it only remains to print them.
For that there is `ff.make_printable_sheets()` that will create print sheets
for arbitrary number of components of arbitrary size (provided they're all the
same size).
Since most of the code is the same as 05, only the start and end which differ
are shown here. See the whole code [here](examples/06_preparing_for_print.py)
```python
from bgfactory import ff
import pangocffi as pango
CARD_WIDTH_MM = 63
CARD_HEIGHT_MM = 88
CARD_RADIUS_MM = 3
DPI = 300
class MyCard(ff.RoundedRectangle):
def __init__(self, x, y, title, description, color=(0.2, 0.3, 0.7)):
pad = 25
super(MyCard, self).__init__(
x, y, ff.mm_to_pixels(CARD_WIDTH_MM, DPI),
ff.mm_to_pixels(CARD_HEIGHT_MM, DPI),
radius=ff.mm_to_pixels(CARD_RADIUS_MM), stroke_width=5,
stroke_src=color, fill_src=ff.COLOR_WHITE,
padding=(pad, pad, pad, pad),
layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER,
valign=ff.VALIGN_TOP)
)
...
# Bunch of code missing, see examples/ for the full code
...
cards = []
for i in range(5):
cards.append(
MyCard(
0, 0,
'Warlock',
'Warlocks are powerful users of magic. It is ancient and its origins are so old that they were long forgotten.'
'\n\nIt was once said, by a particular man, in a particular spot, that in order to find the origin warlock'
' magic, you have to go to the beginning of time, take a right turn, and continue until the edge of space.'
' Those who heard it were as confused as you are.\n\nDespite their power, Warlocks are typically cheerful '
'people, armed with an unexpected arsenal of dad jokes.'
),
)
for i in range(5):
cards.append(
MyCard(
0, 0,
'Rogue',
'Rogues are smart as they are sneaky. They can steal your wallet, your life but also, and not many '
'people know this, also your wife.\n\nThere have been accounts of rogues breaking into a house for a job '
'only to leave with the homeowner\'s wife instead of the loot, never to be found again (though probably'
' somewhere on the Canary Islands).',
color=(0.2, 0.7, 0.3)
),
)
# set your page margins in your program before printing to make sure you get exact measurments on the print
# you can use GIMP to check the actual DPI that's gonna be printed with to see if you have setup everything properly
sheets = ff.make_printable_sheets(cards, dpi=DPI, print_margin_hor_mm=5,
print_margin_ver_mm=5)
# sheets = ff.make_printable_sheets(cards, dpi=DPI, print_margin_hor_mm=5, print_margin_ver_mm=5, out_dir_path='sheets')
for sheet in sheets:
sheet.image().show()
```
- At the start we redefined the dimensions with millimiters and converted to
pixels through DPI, I recommend to use this approach everywhere, this will
make everything parametric and grounded in real units.
- Print sheets is made for A4 paper by default but can be changed
- Print margins are critical for actually hitting the DPI of the print you
wanted. The page margins set here during export and in the program used to
print must be the same, or your real dimensions will be slightly off.
- I personally print through GIMP, since it allows to change margins easily
and also displays horizontal and vertical DPI separately in the print
dialog, which allows me to do a final check that the DPI indeed matches
- I print cards with the same dimension as MtG cards and then use them with
sleeves.
- Notice the last commented line, you can directly save your sheets right with
this function
## Other Functionality
Not everything was covered with these 6 short tutorials, more will be added
in the future. You can always find even more relevant examples in
[tests/](tests/).
## General tips
- I recommend creating a common.py for every project where you define your core
references
- Printing page size (typically A4)
- Printing DPI
- Width and height of your assets in millimiters or inches. Always ground
the
size of your assets in real lengths and then only convert to pixels using
dpi. This will just make your life easier
- General rule of thumb would be: If two templates share a constant (
e.g. width and height), the
constant should be defined only once, probably in common.py
- This way you make sure your design is always fully parametric and you
can tweak even major things as size of your assets, down the line.
If you build your assets smartly, there is a good chance they will
just work with a different dimensions
- board-game-factory is not good at image preprocessing, do this in an external
tool
- for printing always check your page margins match what you set
in `ff.make_printable_sheets`. Otherwise your actual DPI won't be the one
you set and the dimensions will slightly mismatch from what was intended.
- I found google sheets as a great place to actually define the content of my
assets
- I always boil down every asset to a few things that are distinct which are
then parameters for my custom components.
- These fields essentially define a data structure for a given asset
- Then I create a sheet in google sheets with columns matching the data
structure
- Then I use `gspread` to easily download that data into python, and convert
the contents of the spreadsheet into a list of arguments for my template
- Then I just throw them all into `ff.make_printable_sheets` and I'm done.
- This allows me to make all asset changes in one easy to use place and they
propagate instantly to all my cards
## List of Features
(From older version of this readme, keeping it for now)
- High quality rendering - BGF is based fully in Vector Graphics, therefore
allowing for renders of arbitrary resolution
- Component Tree structure - similar to making GUIs in Java, you can embed a
component inside a component inside a component...
- Fully extensible components - the best way to use this framework is to
create and compose your own components extending base components.
- Fully dynamic and highly flexible sizing system:
- Component width/height possible values:
- INFER - the component decides on its own how large it should be
- FILL - fill all available remaining space in the parent Container
- '12.34%' - take up 12.34% of available space
- 123 - take up 123 pixels
- Many basic and advanced components are already implemented:
- Container - base component with a layout manager, you add components into
it.
- Shapes
- Rectangle
- RoundedRectangle
- Circle
- Line
- TextUniform - a fully featured text rendering component (exposing most
advanced features of pango)
for rendering text of a uniform style (all characters have same font,
size, color, ...).
- TextMarkup - advanced text component supporting markup for strings with
multiple styles (boldface words, multiple colors, ...)
- features smart inline laying of icons (any images) for embedding icons
directly in text
- Grid - a special component for creating table structures:
- each cell can have unique parameters (e.g. layout manager)
- incredibly flexible row and column definitions (INFER, FILL, %, px)
- fully featured cell merging
- just with those few components + LayoutManagers I've made all the samples
you can see below in the link on imgur.
- LayoutManagers
- Absolute - define pixels
- HorizontalFlow, VerticalFlow - align automatically to row or column
- Fully extensible, you can write your own
## Short-Term Backlog (look here for easier contributions)
- Improve documentation
- Make auto-generated documentation and host it on readthedocs.io
- wrap all relevant pango constants to hide pango from users altogether
- wrap all relevant cairo constants to hide cairo from users altogether
- margin & padding
- Make them more user friendly
- Currently you always need to provide all 4, make it more like css
- The order is LTRB, whereas in CSS it is TRBL. Something to at least
consider
- Allow % units to be used where possible
- Missing examples:
- Horizontal/VerticalFlowLayout
- TextMarkdown with inline icons
- Grid with merging cells
- Images and fill/stroke sources
- How to write your own reusable components?
- More printing helpers
- Make alternative for CardSheet that doesn't require components of equal
size and rather solves the backpack problem (approximately of course, very
basic heuristics will be enough)
- Make layout validation more transparent. Errors from layout validation are
too cryptic and hard to decode. This is because the layout is very complex
and runs in a tree, following the components. I believe even clearer error
messages are essential to be able to have such a weird myriad of dimension
options, which inevitably produces the option of invalid dynamic sizing
options. Typically the most common issue is where the user creates a cycle
in the tree, where child is inferred from parent and parent from the child.
It's easy to see on the algorithmic level but very hard to intuit when coding.
## Long-Term Backlog of Big Long-Term Things
- basic devops - run tests before pull request merge
- Better wrappers for images in general
- The way images are rendered currently is through using them as a brush to
fill a container or use as a stroke
- This is very flexible and allows crazy things to be done
- However, for the most part, you don't need flexibility, you need a way
to put your picture on a card or perhaps a hex tile and you need it
to "look good" as quickly as possible
- There are a few smart things that can be done
- Basic Image component as a simple wrapper of filling a rectangle
with the image
- It might makes sense to add functionality for working with the
file dimensions here, so INFER option for w,h to get them from
the file. This feature is really important for the highest
fidelity of rendering with PNG assets.
- trimming option to remove any extra background (can be figured out
from top-left pixel, which can be an option to also set it
manually) and create a snug bounding box
- after trimming, the image might no longer be centered as it was,
so additional option could be added to trim, that it would only
always take the same amount from both/all-4 sides. So this way
even a rectangle bbox can be achieved with the original centering.
Very handy in my opinion
- Add `.svg` file support
- With a vector graphics backend it makes a lot of sense for the framework
to be able to handle .svg files
- This could be the easiest way to get super high-fidelity assets since
you can download icons in .svg format and in my own experience, these
icon
databases are the best thing for prototyping
- Best candidate so far: https://github.com/Kozea/CairoSVG
- It's made by the author of cairocffi and seems still very active
- There seems to be a whole xml/html parsing engine which can handle the
html in .svg files, including css styles and more
- Probably no other or better way to do this, simply reuse some of their
internal methods (but ideally external api to prevent silent breaking
changes of this, but that can be handled with an easy version freeze)
- Fix Text components behavior for width='N%' and height=INFER
- Currently, this option will produce un-intuitively wrong results for any
text that doesn't have enough space and needs to do a line break. The text
is likely to overflow the rendering container and therefore be partially
cutoff as a result
- I remember looking closely into this in 2021, and I think I found that
this seemingly simple thing actually cannot be implemented correctly
without fundamentally changing at least some the layout computation model.
- I believe the concrete reason is as follows:
- Text components are currently
the only basic ones (i.e. non-Container children) with unknown
dimensions during render (all other
shapes are defined with pixels or from layout with %, FILL and INFER).
- And the way layout computation flows currently simply doesn't allow
for the relevant information (parent container size) to flow into the
text component.
- This is done via `get_size()` which is an abstract function
of `ff.Component` and as you can see it currently doesn't take any
parameters
- Possible fixes (not sure yet which one should be implemented):
- Just prohibit the use of the option with an error and maybe this will
be good forever?
- Just figure out a way to do `get_size(w, h)` to fill in the dimension
which can already be known before inferring. But this might not be
possible
- Do layout in two passes
- infer all static layout that you can in the first pass (
e.g. `parent.w = ff.INFER, child1.w = 100, child2.w = 150`
-> `parent.w_computed = 250`)
- pass this into text components in the second and fill in all
missing holes
- If neither works the layout algorithm might need a rethink from the
ground-up to understand what's missing and what else needs to be
changed to get this working
- Next steps:
- Do a discovery to once again get a ready understanding of the issue
with a simple testing script + PyCharm debugger
- Based on the findings plan execution
- This should be done as one of the first things as it might require some
rewrite in all components. The longer we wait, the harder it will be
- FlexBoxLayout
- The current layout options do not have a flowing layout that is able to
handle multiple lines of items flowing in the same direction (so multiple
rows of items for HorizontalFlowLayout and similarly for cols for
VerticalFlowLayout).
- I think adding something with very similar options to FlexBox in CSS
should provide all the common layout features also with providing known
options for people who know CSS
- Game Simulator
- cairo and pango are ready-made for real-time rendering, since they are
used
for that in most Linux systems. Therefore, it should be really
straightforward to create a thin wrapper around any component to put it
into
a simulator.
- It would implement only very loose rules on the movement of assets on
the screen
- But being a python framework, it should be quite straightforward to
actually
implement the rules of your game.
- Hmmmm... now that I'm thinking about it... It should be actually easier
than
I thought... This might get more love quite soon, since it would be
invaluable
in prototyping. Just 2 days ago I spent 12 hours cutting out cards because
I happened to create a first prototype that had the minimum of 400
cards :). Not having to print it and play the actual game would be so
sick. Then this would become even more literal board game factory :)
- Actually the whole game engine could be rendered with cairo, even the
non-asset controls, menus, etc. The only thing necessary is an api
to the window manager, to get a window, context menus, rendering canvas
and callback events (both internal and external). All the rendering and
logic could be handled by the board-game-factory.
- The interesting question here is, will it be performant enough by
default without ever being optimized for live rendering?
- I'm curious to see
- And what's even cooler is that this GUI engine could be used directly for
a gui to make the board game prototypes themselves :)
- Oh, and long term, multiplayer would definitely be fun to implement. This
is purely a turn-based multiplayer, so it should be really easy to
achieve, technologically speaking
- Board Game Factory GUI
- After the whole framework is developed enough, it is only natural
to develop a GUI to make this tool accessible en-masse.
- Inevitably, some flexibility will be lost but most can be retained
- Most people don't wanna do crazy stuff anyway, just vary some text and
have a bunch of icons and scale it up proper and that will be most
definitely possible.
- And it could be incredibly useful to everyone. I don't wanna use code
either
if I don't have to. And stuff like csv/json/xml/google sheets imports
would be super easy to make, to allow everyone to scale it all up.
- And with the directly integrated emulator it would be a ride!
- Automated Balance evaluation, update suggestions, possibly using AI
- I have a master degree in artificial intelligence and solving data
problems
with or without AI is my daily bread.
- I also have a lot of interest and a bunch of experience in reinforcement
learning, the field of AI most focused on automatically learning & solving
games
- I've been eyeing different turn-based games over the years, wondering,
if you weren't trying to solve every game ever made, but a specific game,
using the RL tools of today, would it be possible without renting a
data center?
- And I would love to explore this with my own games. However, if a proper
game simulation engine would be developed (which follows naturally from
programming games for playing them with rules), I can definitely see
space for even general solutions, be it basic ones, for auto-balancing
variables
## Things I made with BGF
Samples of prototypes I've made with this framework:
https://imgur.com/a/TS779gR
## Issues
Please report any issues and feel free to try and fix them on your own.
## Contributors Welcome!
I would love to welcome people on board who would like to extend the project
or improve it. I believe we can build a community of people moving this project
forward. I cannot achieve it myself, it's too much work for a free-time
endeavor. As will be for you as well, but together we can meaningfully develop
this into something really, really useful to many more people.
I see a big potential long-term. There are other tools that come close in what
they're trying to do, but I believe none of them is built with production-ready
rendering capabilities.
If we go full crazy and draft some final vision, of what could be in a few
years:
- earliest prototyping
- just create a bunch of cards from a spreadsheet with auto-layout and move
them around in a simulator to test your game basics
- early prototyping
- after first validation and adjustments, it's time to create prototype
visuals, use GUI to build them, import the same data from the spreadsheet
you already have, but this time put it where you want to put it
- add basic icons (there will be a library of free ready-made assets just a
click away)
- do more simulation gameplay
- first paper version
- tweak visuals as needed
- with a few clicks, export print sheets, or even better, print directly
from
the GUI itself, making sure DPI will match etc.
- iterate, iterate, iterate
- when you have a finalized version, start importing production-ready assets
from designers and working on a beautiful, functional and clear layout
- keep using the same spreadsheet from the start
- (optional) - implement rules of your game into the game engine, allow
other
people to play it and give you feedback also online (multiplayer should
definitely be added eventually)
- as your assets get prettier and prettier, so does the simulated version of
your game
- everything is ready for production, sales, propagation
- you export print sheets made to the specifications of devices of your
printing contracts
- all your production assets are automatically available to also play
through
the game engine.
But, one small step at a time. First things first, without community, I won't
come even close.
I would love to hear your ideas and feature requests!
If you're interested you can drop in a PR directly, Issue with a
feature request or reach out to me at adam.volny at gmail dot com.
Raw data
{
"_id": null,
"home_page": "https://github.com/avolny/board-game-factory",
"name": "board-game-factory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Adam Voln\u00fd",
"author_email": "adam.volny@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/e2/055782eb93a9b05126f645e3231982db77b3fc4b8ff35512ebfce87b36ac/board_game_factory-0.3.0.tar.gz",
"platform": null,
"description": "# Board Game Factory\r\n\r\n#### Contributors are welcome here! :) See the last section of this Readme\r\n\r\nThis is a tool for rapid creation of paper prototypes of your cards, tiles,\r\ntokens and sheets.\r\n\r\nHere are samples of what I've made with Board Game Factory:\r\nhttps://imgur.com/a/TS779gR\r\n\r\nI've developed it personally to satisfy my need for a solid prototyping\r\nengine for board games (couldn't find anything that did what I wanted, so I\r\nmade it myself). It can be used just as a simple rendering library for python,\r\nto make whatever you want.\r\n\r\nIt uses vector graphics for rendering (cairo & pango libraries on the backend).\r\n\r\n**DISCLAIMER:** The framework is still under development, it is quite feature\r\ncomplete,\r\nI used it to make and print thousands of cards and other board game assets\r\nalready,\r\nbut from QoL perspective, there are many things that could be improved. So\r\nbefore we\r\nreach version 1.0, expect updates to possibly present breaking changes. We will\r\nkeep it to absolute minimum and do it with consideration, but we want to keep\r\nthis freedom. So\r\nalways update\r\nwith caution, preferably creating a separate venv.\r\n\r\n## Installation\r\n\r\n### 1. Get Pango & Cairo\r\n\r\nPango & Cairo are the only prerequisites that cannot be installed with `pip`.\r\n\r\n#### Windows\r\n\r\nInstall\r\nthis: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer\r\n\r\npango and cairo are included in this GTK+ for Windows Installer, all you need is\r\nto install this on your system. (you can find alternatives too, if you look)\r\n\r\n#### Linux\r\n\r\npango and cairo are most likely installed on your system already (they're at the\r\nheart of GTK). You might need is to install `python-dev` and `libffi-dev` using\r\nyour OS's package manager.\r\n\r\n(This was not tested, I'm referencing cairocffi and pangocffi docs, let me know\r\nif it's inaccurate or doesn't work)\r\n\r\n#### MacOS\r\n\r\n```commandline\r\nbrew install pkg-config\r\nbrew install libffi\r\nbrew install pango\r\nbrew install glib\r\n```\r\n\r\n### 2. Install Board Game Factory\r\n\r\n````commandline\r\npip install board-game-factory\r\n````\r\n\r\n### Having any issues?\r\n\r\n`bgfactory` has the same prerequisites as `cairocffi` and `pangocffi`.\r\n\r\nTake a look at documentation of pangocffi and cairocffi packages (these are the\r\npython bindings into the binaries). Their installation instructions should work:\r\n\r\nhttps://cairocffi.readthedocs.io/en/stable/overview.html#installing-cairocffi\r\nhttps://pangocffi.readthedocs.io/en/latest/overview.html\r\n\r\nIf none of that works for you, create an Issue, describe your issues and all\r\nthat you've tried, and I can take a look at it.\r\n\r\n# Getting Started\r\n\r\nThe following examples are the best documentation to date, contain a lot of\r\nextra context. They also showcase many of the features and how to use them\r\ntogether. So if you want to use this framework for yourself, read carefully\r\nand use this as a reference.\r\n\r\nall code presented below can be found in [examples/](examples/). They\r\npurposefully don't contain a lot of code to be bite-sized and digestable.\r\n\r\n## 01 - The Basics\r\n\r\n[examples/01_basics.py](examples/01_basics.py)\r\n\r\nLet's draw our first thing.\r\n\r\n```python\r\nfrom bgfactory import ff\r\n\r\ncomponent = ff.RoundedRectangle(0, 0, 300, 200, radius=60, stroke_width=15,\r\n stroke_src=(0.2, 0.3, 0.7),\r\n fill_src=ff.COLOR_WHITE)\r\n\r\ncomponent.image().show()\r\n\r\ncomponent.image().save('image.png')\r\n```\r\n\r\nThe code above creates a rounded rectangle component, shows it on screen and\r\nsaves it to a png.\r\n\r\nYou should see this:\r\n\r\n![](assets/readme/example01.png \"Image\")\r\n\r\nAll drawing in the framework is done using components.\r\n\r\nThey represent everything elementary that's going to be drawn:\r\n\r\n- a line or a rectangle\r\n- piece of text\r\n- ...\r\n\r\nAll components take `x, y` coordinates as their first arguments. What follows\r\nis always definition of dimensions where suitable, `w, h` for most components\r\nbut e.g. circle is defined with `x, y, radius` instead of `x, y, w, h`.\r\n\r\nThe unit here is pixels. Even though on the backend vector graphics is used\r\nwith infinite resolution, you still need to ground the coordinate system in\r\nsomething and pixels here are the most natural since they then correspond 1:1\r\nwith the dimensions of rendered images.\r\n\r\nEvery component extends `ff.Component` which also in turn allows to\r\nuse `.image()`\r\non every component. It returns a PIL.Image, which you\r\ncan easily manipulate further, most often with show or save.\r\n\r\nThis is very convenient, you have instant visual debugging for everything, even\r\nyour own components.\r\n\r\n## 02 - Containers & Shapes\r\n\r\n[examples/02_containers_and_shapes.py](examples/02_containers_and_shapes.py)\r\n\r\nIn order to make more complicated components you need some place to put them\r\ntogether into and that's what containers are for.\r\n\r\nContainers allow components to have descendants (we call them children here)\r\nthat render inside them.\r\n\r\nUnlike for the `Component` base class, you will find yourself using the base\r\n`Container` quite often, since it represents a rectangle container that has\r\nno fill or border.\r\n\r\nWe use it here to showcase all the shapes and put them together in one picture.\r\nIn the beginning we add a white square to the middle for better visibility\r\nno matter your background.\r\n\r\n```python\r\nfrom bgfactory import ff\r\n\r\n# colors can be 3-tuple or 4-tuple of values between 0 and 1\r\nCOLOR1 = (232 / 255, 131 / 255, 7 / 255)\r\nCOLOR2 = (33 / 255, 196 / 255, 131 / 255)\r\nCOLOR3 = (32 / 255, 65 / 255, 212 / 255)\r\nCOLOR4_SEMITRANSPARENT = (32 / 255, 65 / 255, 212 / 255, 128 / 255)\r\nCOLOR5_SEMITRANSPARENT = (180 / 255, 60 / 255, 64 / 255, 128 / 255)\r\n\r\n# for shapes: stroke = border, fill = inside\r\ncontainer = ff.Container(\r\n 0, 0, 400, 400,\r\n children=[\r\n ff.Rectangle(50, 50, 350, 350, fill_src=ff.COLOR_WHITE, stroke_width=0),\r\n ff.Line(20, 380, 380, 20, stroke_width=5, stroke_src=COLOR3),\r\n ff.Circle(140, 140, 80, stroke_width=5, stroke_src=COLOR1,\r\n fill_src=COLOR2),\r\n ff.RoundedRectangle(20, 20, 230, 230, stroke_width=5, stroke_src=COLOR1,\r\n fill_src=ff.COLOR_TRANSPARENT),\r\n ]\r\n)\r\ncontainer.add(\r\n ff.RegularPolygon(130, 260, 40, 5, fill_src=COLOR4_SEMITRANSPARENT,\r\n stroke_width=0),\r\n ff.RegularPolygon(160, 220, 80, 6, fill_src=COLOR5_SEMITRANSPARENT,\r\n stroke_width=0)\r\n)\r\n\r\ncontainer.image().show()\r\n```\r\n\r\nCouple of things to note:\r\n\r\n- notice 2 ways of adding components to a container, you can use either or both.\r\n- all shapes extend `Container`, not `Component`, so you can easily put shapes\r\n into other shapes.\r\n- note the way the colors are defined, they have to be a 3-tuple or a 4-tuple of\r\n floats between 0 and 1. The 4th channel represents transparency\r\n - there is a good reason why the arguments are called stroke_src, fill_src\r\n and not\r\n stroke_color, fill_color. That's because the arguments are way more\r\n flexible, imagine source\r\n as being an image and the area to be filled simply a mask on this image.\r\n For\r\n a fixed color this corresponds to a filled rectangle, so you get the same\r\n color everywhere. But you can for example also use any color gradient (\r\n composed of arbitrary many colors) or even any image.\r\n - So most of the time, src=color, but sometimes it allows you to do crazy\r\n stuff\r\n- notice that the order in which components are added they are also rendered\r\n- `Container` cannot have any stroke or fill. If you need them, simply\r\n use `Rectangle` instead, they are equivalent in every other way.\r\n\r\nAnd finally, what you should see:\r\n\r\n![](assets/readme/example02.png \"Image\")\r\n\r\n## 03 - Uniform Text and Alignment\r\n\r\nNow let's see how do you render text. cairo is used for text rendering too,\r\nhowever to get the render path, pango is used. General-purpose text rendering\r\nis an incredibly complex problem with the amount of writing systems worldwide.\r\nSince pango is at the core rendering engine of many Linux distributions,\r\npango can handle everything, any font, any locale, any writing system.\r\n\r\n(In other words if some feature you would want is missing, write a feature\r\nrequest, please :)\r\n\r\nFor text rendering, there are 2 components available at the moment:\r\n`TextUniform` and `TextMarkup`. Their crucial difference is that `TextUniform`\r\nimposes the same style on the whole text that's being rendered, whereas\r\n`TextMarkup` allows you to mark the text with html tags to modify the style and\r\nbeyond that it has a feature of inlaying any Component directly into the text,\r\nwhich is priceless when you want e.g. resource icons to be directly in text of\r\ncard descriptions.\r\n\r\nHere we will take a look at the simpler one: `TextUniform`\r\n\r\nIn the following code, pay attention to a few things:\r\n\r\n- we are importing pango as well as bgfactory\r\n - pango is used for constants in `ff.FontDescription` (and nothing else from\r\n user perspective)\r\n - (these might get wrapped in the future so you don't have to deal with\r\n this)\r\n- the dimensions and coordinates are now parametric, we are taking advantage of\r\n python being a\r\n general purpose language to make adjusting our components as easy as possible.\r\n The most efficient way to use this framework is to make everything parametric,\r\n then you can change hundreds of assets significantly with 1 line change.\r\n- you can define both stroke and fill on text. by default you get no stroke and\r\n black fill, which is how text is rendered by default anywhere.\r\n- we are defining text alignment (since the text component is given more space\r\n than it can use, we have to tell it how to align itself, default is top-left)\r\n- it can handle newlines with ease\r\n\r\n[examples/03_text_and_alignment.py](examples/03_text_and_alignment.py)\r\n\r\n```python\r\nfrom bgfactory import ff\r\nimport pangocffi as pango\r\n\r\nw = 500\r\nh = 350\r\npadding = 60\r\n\r\ncontainer = ff.RoundedRectangle(\r\n 0, 0, w, h, radius=60,\r\n stroke_width=15, stroke_src=(0.2, 0.3, 0.7), fill_src=ff.COLOR_WHITE)\r\n\r\ncontainer.add(\r\n ff.TextUniform(\r\n padding, padding, w - 2 * padding, h - 2 * padding,\r\n \"Hello from Board Game Factory!\\n\\nHow are you doing today?\",\r\n fill_src=(0.2, 0.6, 0.9),\r\n stroke_width=1,\r\n stroke_src=ff.COLOR_BLACK,\r\n font_description=ff.FontDescription(\r\n family='Arial',\r\n size=w * 0.06,\r\n weight=pango.Weight.BOLD,\r\n style=pango.Style.ITALIC,\r\n ),\r\n halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_MIDDLE\r\n )\r\n)\r\n\r\ncontainer.image().show()\r\n```\r\n\r\nNotes:\r\n\r\n- the names of the arguments of `FontDescription` always correspond 1:1 to a\r\n pango namespace with relevant constants, so it shouldn't be too much of a\r\n hassle using it\r\n- you can also tweak character spacing as `stretch` in `ff.FontDescription` and\r\n line spacing with `spacing` directly in `ff.TextUniform`.\r\n- to install new fonts simply install them to your operating system\r\n - if not sure where to get good fonts -> https://fonts.google.com/\r\n\r\nWhat you should see:\r\n\r\n![](assets/readme/example03.png \"Image\")\r\n\r\n## 04 - Layout Managers and Dynamic Size\r\n\r\n[examples/04_layout_and_infer_size.py](examples/04_layout_and_infer_size.py)\r\n\r\nParametric layout is nice but still insufficient if you want to create asset\r\ntemplates, rather than assets. And with a template, you don't necessarily know\r\nthe dimensions of your content.\r\n\r\nEspecially text will fluctuate in dimensions and often you don't want to take up\r\na lot of space, just in case there would be a lot of text.\r\n\r\nWhat you would ideally want is some sort of dynamic layout which adjusts based\r\non the size of the content. You ultimately want the same layout options as in a\r\nweb-browser.\r\n\r\nFor this purpose, the base class `ff.LayoutManager` was created.\r\nLayout manager is a part of every `ff.Container` (even when not seen by you).\r\n\r\nWhen a container is being drawn, first its layout manager decides what is the\r\nposition and size of each child and only then are they drawn.\r\nThis allows not only for dynamic positioning but also dimensions.\r\n\r\nThe default layout manager that we were using so far, without knowing it,\r\nis the `ff.AbsoluteLayout`. This is a very simple one, it just expects every\r\ncomponent to know its `x, y, w, h` beforehand and just places them accordingly.\r\n\r\nFor the dynamic behavior, currently 2 layout managers are implemented to\r\nfacilitate this:\r\n\r\n- `ff.VerticalFlowLayout`\r\n- `ff.HorizontalFlowLayout`\r\n\r\nThey are exactly the same, only one stacks items in the horizontal direction\r\nand the other in the vertical.\r\n\r\nLet's get to the example before explaining more:\r\n\r\n```python\r\nfrom bgfactory import ff\r\nimport pangocffi as pango\r\n\r\nw = 400\r\nh = 600\r\n\r\ncolor = (0.2, 0.3, 0.7)\r\n\r\ncontainer = ff.RoundedRectangle(\r\n 0, 0, w, h, radius=30, stroke_width=5, stroke_src=color,\r\n fill_src=ff.COLOR_WHITE,\r\n padding=(30, 30, 30, 30),\r\n layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER, valign=ff.VALIGN_TOP)\r\n)\r\n\r\ncontainer.add(\r\n ff.TextUniform(\r\n 0, 0, w * 0.8, ff.INFER,\r\n \"Card Title\",\r\n font_description=ff.FontDescription(\r\n family='Arial',\r\n size=w * 0.1,\r\n weight=pango.Weight.BOLD,\r\n style=pango.Style.NORMAL,\r\n ),\r\n halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_MIDDLE\r\n ),\r\n ff.TextUniform(\r\n 0, 0, w * 0.8, ff.INFER,\r\n \"This is a rather long card description. It contains multiple paragraphs that need to fit.\"\r\n \"\\n\\nWhen I wrote this, I wasn't quite sure how much space this will take.\"\r\n \"\\n\\nThat's when ff.INFER gets super handy!\",\r\n font_description=ff.FontDescription(\r\n family='Arial',\r\n size=w * 0.05,\r\n weight=pango.Weight.NORMAL,\r\n style=pango.Style.OBLIQUE,\r\n ),\r\n halign=ff.HALIGN_LEFT,\r\n valign=ff.VALIGN_MIDDLE,\r\n margin=(0, h * 0.1, 0, 0)\r\n ),\r\n ff.Container(\r\n 0, 0, '100%', ff.FILL,\r\n layout=ff.HorizontalFlowLayout(halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_MIDDLE),\r\n children=[\r\n ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=1,\r\n fill_src=ff.COLOR_TRANSPARENT, stroke_src=color),\r\n ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=0,\r\n fill_src=ff.COLOR_TRANSPARENT, stroke_src=color),\r\n ff.RegularPolygon(0, 0, h * 0.05, num_points=3, rotation=1,\r\n fill_src=ff.COLOR_TRANSPARENT, stroke_src=color)\r\n ]\r\n )\r\n)\r\n\r\ncontainer.image().show()\r\n```\r\n\r\n(see the render below)\r\n\r\n- Notice we added `ff.VerticalFlowLayout` to the main container\r\n and `ff.HorizontalFlowLayout` to the bottom one. So you can combine different\r\n layout managers in hierarchies to get the desired layout\r\n- All components that are children of a container\r\n with `Horizontal/VerticalFlowLayout`\r\n have their `x, y` coordinates ignored as the responsibility of positioning\r\n is delegated to the given layout manager.\r\n- Some width and heights have now weird values, let's go through them and their\r\n intricacies (these are really key to understand, you will use them all the\r\n time):\r\n - `INFER` - used on the height of both of the text blocks. Both text fields\r\n have fixed width, and then the pango backend is used to figure out how\r\n tall will a given text be. This is then used during render.\r\n - This can also be used on any container's width/height with these\r\n dynamic flow layouts, because its children can tell it its size\r\n - `'100%'` - means, to take up 100% of space of the parent container, can be\r\n arbitrary float between 0 and 100, but is kept a string for clarity of\r\n units, e.g. `'5%'` or `'3.1415%'`\r\n - Cannot be used in conjunction with INFER of the same dimension on the\r\n parent container. This creates a cyclic dependency. The validation\r\n will crash\r\n - `FILL` - fills the remaining area of the container\r\n - for the dimension in flow direction, e.g. width\r\n for `HorizontalFlowLayout` this can be used only on the last child to\r\n fill the remaining width of the container. Analogously\r\n for `height=FILL` and `VerticalFlowLayout`\r\n - for the other dimension, it simply sets it to `'100%'`, filling the\r\n whole available container space\r\n- Each of them have `halign, valign` - they work as expected,\r\n horizontal and vertical alignment of children in the layout\r\n- Also notice `padding` and `margin`. These have the same definitions as in CSS.\r\n - `padding` is like invisible internal border of a container. It pads the\r\n children from all sides\r\n - `margin` defines spacing between children of a container. Every child have\r\n their own margins, however, just like with CSS, overlapping margins don't\r\n add up. So if you define a margin of 10 pixels for every child, the space\r\n between children will be 10px, not 20px. It always picks the bigger\r\n margin. Note that this interaction doesn't happen with padding, padding\r\n and margin stack as you would expect normally.\r\n - they are defined with a 4-tuple, representing\r\n order: `left, top, right, bottom`\r\n - This is different from for example CSS, however it seemed more\r\n intuitive\r\n to me, as left and margins are typically the most important\r\n\r\nLayout managers are the main source of flexibility and also complexity.\r\nUse them wisely, they are definitely not needed every time. Very often the\r\ndefault `AbsoluteLayout` in conjunction with parametric positioning is what\r\nyou want, only using flowy layout when you have text of significant variation\r\nand/or need components to maintain spacing after dynamic text.\r\n\r\nAlso, there is one more layout option, check out `ff.Grid`, it doesn't adhere\r\nto the `LayoutManager` pattern but does the same thing differently (see tests\r\nfor more detail before a tutorial on it is written)\r\n\r\nFinally, the render result:\r\n\r\n![](assets/readme/example04.png \"Image\")\r\n\r\n## 05 - Making your first template!\r\n\r\n[examples/05_making_your_own_component.py](examples/05_making_your_own_component.py)\r\n\r\nAfter you achieve the structure you wanted, it's time to package things up for\r\nreuse. The intended usage pattern of board-game-factory is for you to create\r\nyour own component class, that will extend\r\ntypically `Container, RoudnedRectangle, Rectangle, ...` and you build the layout\r\nin the constructor of such component. It also takes all necessary variables as\r\nconstructor params.\r\n\r\nPackaging your components like this and always extending from `Component` makes\r\nsure your components can always be defined just by the simple interface and\r\ntherefore can be used as a part of other components freely.\r\n\r\nThe following code does the same thing, but now the title and text are arguments\r\nof our own `MyCard` component which we can render using `.image().show()` as\r\nany component.\r\n\r\n```python\r\nfrom bgfactory import ff\r\nimport pangocffi as pango\r\n\r\nCARD_WIDTH = 400\r\nCARD_HEIGHT = 600\r\n\r\n\r\nclass MyCard(ff.RoundedRectangle):\r\n\r\n def __init__(self, x, y, title, description, color=(0.2, 0.3, 0.7)):\r\n pad = 25\r\n\r\n super(MyCard, self).__init__(\r\n x, y, CARD_WIDTH, CARD_HEIGHT, radius=30, stroke_width=5,\r\n stroke_src=color, fill_src=ff.COLOR_WHITE,\r\n padding=(pad, pad, pad, pad),\r\n layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_TOP)\r\n )\r\n\r\n self.add(\r\n ff.TextUniform(\r\n 0, 0, self.w * 0.8, ff.INFER,\r\n title,\r\n font_description=ff.FontDescription(\r\n family='Arial',\r\n size=self.w * 0.1,\r\n weight=pango.Weight.BOLD,\r\n style=pango.Style.NORMAL,\r\n ),\r\n halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_MIDDLE,\r\n )\r\n )\r\n\r\n self.add(\r\n ff.TextUniform(\r\n 0, 0, self.w * 0.8, ff.INFER,\r\n description,\r\n font_description=ff.FontDescription(\r\n family='Arial',\r\n size=self.w * 0.045,\r\n weight=pango.Weight.NORMAL,\r\n style=pango.Style.OBLIQUE,\r\n ),\r\n halign=ff.HALIGN_LEFT,\r\n valign=ff.VALIGN_MIDDLE,\r\n margin=(0, pad, 0, pad)\r\n )\r\n )\r\n\r\n bottom_panel = ff.Container(\r\n 0, 0, '100%', ff.FILL,\r\n layout=ff.HorizontalFlowLayout(halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_MIDDLE)\r\n )\r\n\r\n bottom_panel.add(\r\n ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=1,\r\n fill_src=ff.COLOR_TRANSPARENT,\r\n stroke_src=color),\r\n ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=0,\r\n fill_src=ff.COLOR_TRANSPARENT,\r\n stroke_src=color),\r\n ff.RegularPolygon(0, 0, self.h * 0.05, num_points=3, rotation=1,\r\n fill_src=ff.COLOR_TRANSPARENT,\r\n stroke_src=color)\r\n )\r\n\r\n self.add(bottom_panel)\r\n\r\n\r\ncontainer = ff.Container(\r\n 0, 0, 2 * CARD_WIDTH, CARD_HEIGHT\r\n)\r\n\r\ncontainer.add(\r\n MyCard(\r\n 0, 0,\r\n 'Warlock',\r\n 'Warlocks are powerful users of magic. It is ancient and its origins are so old that they were long forgotten.'\r\n '\\n\\nIt was once said, by a particular man, in a particular spot, that in order to find the origin warlock'\r\n ' magic, you have to go to the beginning of time, take a right turn, and continue until the edge of space.'\r\n ' Those who heard it were as confused as you are.\\n\\nDespite their power, Warlocks are typically cheerful '\r\n 'people, armed with an unexpected arsenal of dad jokes.'\r\n ),\r\n MyCard(\r\n CARD_WIDTH, 0,\r\n 'Rogue',\r\n 'Rogues are smart as they are sneaky. They can steal your wallet, your life but also, and not many '\r\n 'people know this, also your wife.\\n\\nThere have been accounts of rogues breaking into a house for a job '\r\n 'only to leave with the homeowner\\'s wife instead of the loot, never to be found again (though probably'\r\n ' somewhere on the Canary Islands).',\r\n color=(0.2, 0.7, 0.3)\r\n ),\r\n)\r\n\r\ncontainer.image().show()\r\n```\r\n\r\nYou can see that after defining our template with a class, we have abstracted\r\nall of that dense text away and are left with just the things we want to tweak;\r\ntitle, description and color.\r\n\r\nAnd instantly we can render 2 different cards with the same layout just\r\nwith a few lines of code.\r\n\r\nYou would probably want to initialize these objects from a spreadsheet or a csv\r\nfile. I use google sheets myself to define all the dynamic content of all my\r\nassets and load it in python using `gspread`. It works really well, I just\r\nchange some values in google sheets, press a button and instantly have a\r\nbrand new set of print sheets ready with the changes incorporated into all\r\naffected assets.\r\n\r\nOur result:\r\n\r\n![](assets/readme/example05.png \"Image\")\r\n\r\n## 06 - How to scale it up and export for printing?\r\n\r\n[examples/06_preparing_for_print.py](examples/06_preparing_for_print.py)\r\n\r\nNow that we have our asset templates designed and populated with content,\r\nit only remains to print them.\r\n\r\nFor that there is `ff.make_printable_sheets()` that will create print sheets\r\nfor arbitrary number of components of arbitrary size (provided they're all the\r\nsame size).\r\n\r\nSince most of the code is the same as 05, only the start and end which differ\r\nare shown here. See the whole code [here](examples/06_preparing_for_print.py)\r\n\r\n```python\r\n\r\nfrom bgfactory import ff\r\nimport pangocffi as pango\r\n\r\nCARD_WIDTH_MM = 63\r\nCARD_HEIGHT_MM = 88\r\nCARD_RADIUS_MM = 3\r\nDPI = 300\r\n\r\n\r\nclass MyCard(ff.RoundedRectangle):\r\n\r\n def __init__(self, x, y, title, description, color=(0.2, 0.3, 0.7)):\r\n pad = 25\r\n\r\n super(MyCard, self).__init__(\r\n x, y, ff.mm_to_pixels(CARD_WIDTH_MM, DPI),\r\n ff.mm_to_pixels(CARD_HEIGHT_MM, DPI),\r\n radius=ff.mm_to_pixels(CARD_RADIUS_MM), stroke_width=5,\r\n stroke_src=color, fill_src=ff.COLOR_WHITE,\r\n padding=(pad, pad, pad, pad),\r\n layout=ff.VerticalFlowLayout(halign=ff.HALIGN_CENTER,\r\n valign=ff.VALIGN_TOP)\r\n )\r\n\r\n\r\n...\r\n# Bunch of code missing, see examples/ for the full code\r\n...\r\n\r\ncards = []\r\n\r\nfor i in range(5):\r\n cards.append(\r\n MyCard(\r\n 0, 0,\r\n 'Warlock',\r\n 'Warlocks are powerful users of magic. It is ancient and its origins are so old that they were long forgotten.'\r\n '\\n\\nIt was once said, by a particular man, in a particular spot, that in order to find the origin warlock'\r\n ' magic, you have to go to the beginning of time, take a right turn, and continue until the edge of space.'\r\n ' Those who heard it were as confused as you are.\\n\\nDespite their power, Warlocks are typically cheerful '\r\n 'people, armed with an unexpected arsenal of dad jokes.'\r\n ),\r\n )\r\n\r\nfor i in range(5):\r\n cards.append(\r\n MyCard(\r\n 0, 0,\r\n 'Rogue',\r\n 'Rogues are smart as they are sneaky. They can steal your wallet, your life but also, and not many '\r\n 'people know this, also your wife.\\n\\nThere have been accounts of rogues breaking into a house for a job '\r\n 'only to leave with the homeowner\\'s wife instead of the loot, never to be found again (though probably'\r\n ' somewhere on the Canary Islands).',\r\n color=(0.2, 0.7, 0.3)\r\n ),\r\n )\r\n\r\n# set your page margins in your program before printing to make sure you get exact measurments on the print\r\n# you can use GIMP to check the actual DPI that's gonna be printed with to see if you have setup everything properly\r\nsheets = ff.make_printable_sheets(cards, dpi=DPI, print_margin_hor_mm=5,\r\n print_margin_ver_mm=5)\r\n\r\n# sheets = ff.make_printable_sheets(cards, dpi=DPI, print_margin_hor_mm=5, print_margin_ver_mm=5, out_dir_path='sheets')\r\n\r\nfor sheet in sheets:\r\n sheet.image().show()\r\n\r\n```\r\n\r\n- At the start we redefined the dimensions with millimiters and converted to\r\n pixels through DPI, I recommend to use this approach everywhere, this will\r\n make everything parametric and grounded in real units.\r\n- Print sheets is made for A4 paper by default but can be changed\r\n- Print margins are critical for actually hitting the DPI of the print you\r\n wanted. The page margins set here during export and in the program used to\r\n print must be the same, or your real dimensions will be slightly off.\r\n - I personally print through GIMP, since it allows to change margins easily\r\n and also displays horizontal and vertical DPI separately in the print\r\n dialog, which allows me to do a final check that the DPI indeed matches\r\n - I print cards with the same dimension as MtG cards and then use them with\r\n sleeves.\r\n- Notice the last commented line, you can directly save your sheets right with\r\n this function\r\n\r\n![](assets/readme/example06_1.png \"Image\")\r\n\r\n## Other Functionality\r\n\r\nNot everything was covered with these 6 short tutorials, more will be added\r\nin the future. You can always find even more relevant examples in\r\n[tests/](tests/).\r\n\r\n## General tips\r\n\r\n- I recommend creating a common.py for every project where you define your core\r\n references\r\n - Printing page size (typically A4)\r\n - Printing DPI\r\n - Width and height of your assets in millimiters or inches. Always ground\r\n the\r\n size of your assets in real lengths and then only convert to pixels using\r\n dpi. This will just make your life easier\r\n - General rule of thumb would be: If two templates share a constant (\r\n e.g. width and height), the\r\n constant should be defined only once, probably in common.py\r\n - This way you make sure your design is always fully parametric and you\r\n can tweak even major things as size of your assets, down the line.\r\n If you build your assets smartly, there is a good chance they will\r\n just work with a different dimensions\r\n- board-game-factory is not good at image preprocessing, do this in an external\r\n tool\r\n- for printing always check your page margins match what you set\r\n in `ff.make_printable_sheets`. Otherwise your actual DPI won't be the one\r\n you set and the dimensions will slightly mismatch from what was intended.\r\n- I found google sheets as a great place to actually define the content of my\r\n assets\r\n - I always boil down every asset to a few things that are distinct which are\r\n then parameters for my custom components.\r\n - These fields essentially define a data structure for a given asset\r\n - Then I create a sheet in google sheets with columns matching the data\r\n structure\r\n - Then I use `gspread` to easily download that data into python, and convert\r\n the contents of the spreadsheet into a list of arguments for my template\r\n - Then I just throw them all into `ff.make_printable_sheets` and I'm done.\r\n - This allows me to make all asset changes in one easy to use place and they\r\n propagate instantly to all my cards\r\n\r\n## List of Features\r\n\r\n(From older version of this readme, keeping it for now)\r\n\r\n- High quality rendering - BGF is based fully in Vector Graphics, therefore\r\n allowing for renders of arbitrary resolution\r\n- Component Tree structure - similar to making GUIs in Java, you can embed a\r\n component inside a component inside a component...\r\n- Fully extensible components - the best way to use this framework is to\r\n create and compose your own components extending base components.\r\n- Fully dynamic and highly flexible sizing system:\r\n - Component width/height possible values:\r\n - INFER - the component decides on its own how large it should be\r\n - FILL - fill all available remaining space in the parent Container\r\n - '12.34%' - take up 12.34% of available space\r\n - 123 - take up 123 pixels\r\n- Many basic and advanced components are already implemented:\r\n - Container - base component with a layout manager, you add components into\r\n it.\r\n - Shapes\r\n - Rectangle\r\n - RoundedRectangle\r\n - Circle\r\n - Line\r\n - TextUniform - a fully featured text rendering component (exposing most\r\n advanced features of pango)\r\n for rendering text of a uniform style (all characters have same font,\r\n size, color, ...).\r\n - TextMarkup - advanced text component supporting markup for strings with\r\n multiple styles (boldface words, multiple colors, ...)\r\n - features smart inline laying of icons (any images) for embedding icons\r\n directly in text\r\n - Grid - a special component for creating table structures:\r\n - each cell can have unique parameters (e.g. layout manager)\r\n - incredibly flexible row and column definitions (INFER, FILL, %, px)\r\n - fully featured cell merging\r\n - just with those few components + LayoutManagers I've made all the samples\r\n you can see below in the link on imgur.\r\n- LayoutManagers\r\n - Absolute - define pixels\r\n - HorizontalFlow, VerticalFlow - align automatically to row or column\r\n - Fully extensible, you can write your own\r\n\r\n## Short-Term Backlog (look here for easier contributions)\r\n\r\n- Improve documentation\r\n- Make auto-generated documentation and host it on readthedocs.io\r\n- wrap all relevant pango constants to hide pango from users altogether\r\n- wrap all relevant cairo constants to hide cairo from users altogether\r\n- margin & padding\r\n - Make them more user friendly\r\n - Currently you always need to provide all 4, make it more like css\r\n - The order is LTRB, whereas in CSS it is TRBL. Something to at least\r\n consider\r\n - Allow % units to be used where possible\r\n- Missing examples:\r\n - Horizontal/VerticalFlowLayout\r\n - TextMarkdown with inline icons\r\n - Grid with merging cells\r\n - Images and fill/stroke sources\r\n - How to write your own reusable components?\r\n- More printing helpers\r\n - Make alternative for CardSheet that doesn't require components of equal\r\n size and rather solves the backpack problem (approximately of course, very\r\n basic heuristics will be enough)\r\n- Make layout validation more transparent. Errors from layout validation are\r\n too cryptic and hard to decode. This is because the layout is very complex\r\n and runs in a tree, following the components. I believe even clearer error\r\n messages are essential to be able to have such a weird myriad of dimension\r\n options, which inevitably produces the option of invalid dynamic sizing\r\n options. Typically the most common issue is where the user creates a cycle\r\n in the tree, where child is inferred from parent and parent from the child.\r\n It's easy to see on the algorithmic level but very hard to intuit when coding.\r\n\r\n## Long-Term Backlog of Big Long-Term Things\r\n\r\n- basic devops - run tests before pull request merge\r\n\r\n- Better wrappers for images in general\r\n - The way images are rendered currently is through using them as a brush to\r\n fill a container or use as a stroke\r\n - This is very flexible and allows crazy things to be done\r\n - However, for the most part, you don't need flexibility, you need a way\r\n to put your picture on a card or perhaps a hex tile and you need it\r\n to \"look good\" as quickly as possible\r\n - There are a few smart things that can be done\r\n - Basic Image component as a simple wrapper of filling a rectangle\r\n with the image\r\n - It might makes sense to add functionality for working with the\r\n file dimensions here, so INFER option for w,h to get them from\r\n the file. This feature is really important for the highest\r\n fidelity of rendering with PNG assets.\r\n - trimming option to remove any extra background (can be figured out\r\n from top-left pixel, which can be an option to also set it\r\n manually) and create a snug bounding box\r\n - after trimming, the image might no longer be centered as it was,\r\n so additional option could be added to trim, that it would only\r\n always take the same amount from both/all-4 sides. So this way\r\n even a rectangle bbox can be achieved with the original centering.\r\n Very handy in my opinion\r\n- Add `.svg` file support\r\n - With a vector graphics backend it makes a lot of sense for the framework\r\n to be able to handle .svg files\r\n - This could be the easiest way to get super high-fidelity assets since\r\n you can download icons in .svg format and in my own experience, these\r\n icon\r\n databases are the best thing for prototyping\r\n - Best candidate so far: https://github.com/Kozea/CairoSVG\r\n - It's made by the author of cairocffi and seems still very active\r\n - There seems to be a whole xml/html parsing engine which can handle the\r\n html in .svg files, including css styles and more\r\n - Probably no other or better way to do this, simply reuse some of their\r\n internal methods (but ideally external api to prevent silent breaking\r\n changes of this, but that can be handled with an easy version freeze)\r\n\r\n- Fix Text components behavior for width='N%' and height=INFER\r\n - Currently, this option will produce un-intuitively wrong results for any\r\n text that doesn't have enough space and needs to do a line break. The text\r\n is likely to overflow the rendering container and therefore be partially\r\n cutoff as a result\r\n - I remember looking closely into this in 2021, and I think I found that\r\n this seemingly simple thing actually cannot be implemented correctly\r\n without fundamentally changing at least some the layout computation model.\r\n - I believe the concrete reason is as follows:\r\n - Text components are currently\r\n the only basic ones (i.e. non-Container children) with unknown\r\n dimensions during render (all other\r\n shapes are defined with pixels or from layout with %, FILL and INFER).\r\n - And the way layout computation flows currently simply doesn't allow\r\n for the relevant information (parent container size) to flow into the\r\n text component.\r\n - This is done via `get_size()` which is an abstract function\r\n of `ff.Component` and as you can see it currently doesn't take any\r\n parameters\r\n - Possible fixes (not sure yet which one should be implemented):\r\n - Just prohibit the use of the option with an error and maybe this will\r\n be good forever?\r\n - Just figure out a way to do `get_size(w, h)` to fill in the dimension\r\n which can already be known before inferring. But this might not be\r\n possible\r\n - Do layout in two passes\r\n - infer all static layout that you can in the first pass (\r\n e.g. `parent.w = ff.INFER, child1.w = 100, child2.w = 150`\r\n -> `parent.w_computed = 250`)\r\n - pass this into text components in the second and fill in all\r\n missing holes\r\n - If neither works the layout algorithm might need a rethink from the\r\n ground-up to understand what's missing and what else needs to be\r\n changed to get this working\r\n - Next steps:\r\n - Do a discovery to once again get a ready understanding of the issue\r\n with a simple testing script + PyCharm debugger\r\n - Based on the findings plan execution\r\n - This should be done as one of the first things as it might require some\r\n rewrite in all components. The longer we wait, the harder it will be\r\n\r\n- FlexBoxLayout\r\n - The current layout options do not have a flowing layout that is able to\r\n handle multiple lines of items flowing in the same direction (so multiple\r\n rows of items for HorizontalFlowLayout and similarly for cols for\r\n VerticalFlowLayout).\r\n - I think adding something with very similar options to FlexBox in CSS\r\n should provide all the common layout features also with providing known\r\n options for people who know CSS\r\n\r\n- Game Simulator\r\n - cairo and pango are ready-made for real-time rendering, since they are\r\n used\r\n for that in most Linux systems. Therefore, it should be really\r\n straightforward to create a thin wrapper around any component to put it\r\n into\r\n a simulator.\r\n - It would implement only very loose rules on the movement of assets on\r\n the screen\r\n - But being a python framework, it should be quite straightforward to\r\n actually\r\n implement the rules of your game.\r\n - Hmmmm... now that I'm thinking about it... It should be actually easier\r\n than\r\n I thought... This might get more love quite soon, since it would be\r\n invaluable\r\n in prototyping. Just 2 days ago I spent 12 hours cutting out cards because\r\n I happened to create a first prototype that had the minimum of 400\r\n cards :). Not having to print it and play the actual game would be so\r\n sick. Then this would become even more literal board game factory :)\r\n - Actually the whole game engine could be rendered with cairo, even the\r\n non-asset controls, menus, etc. The only thing necessary is an api\r\n to the window manager, to get a window, context menus, rendering canvas\r\n and callback events (both internal and external). All the rendering and\r\n logic could be handled by the board-game-factory.\r\n - The interesting question here is, will it be performant enough by\r\n default without ever being optimized for live rendering?\r\n - I'm curious to see\r\n - And what's even cooler is that this GUI engine could be used directly for\r\n a gui to make the board game prototypes themselves :)\r\n - Oh, and long term, multiplayer would definitely be fun to implement. This\r\n is purely a turn-based multiplayer, so it should be really easy to\r\n achieve, technologically speaking\r\n\r\n\r\n- Board Game Factory GUI\r\n - After the whole framework is developed enough, it is only natural\r\n to develop a GUI to make this tool accessible en-masse.\r\n - Inevitably, some flexibility will be lost but most can be retained\r\n - Most people don't wanna do crazy stuff anyway, just vary some text and\r\n have a bunch of icons and scale it up proper and that will be most\r\n definitely possible.\r\n - And it could be incredibly useful to everyone. I don't wanna use code\r\n either\r\n if I don't have to. And stuff like csv/json/xml/google sheets imports\r\n would be super easy to make, to allow everyone to scale it all up.\r\n - And with the directly integrated emulator it would be a ride!\r\n\r\n\r\n- Automated Balance evaluation, update suggestions, possibly using AI\r\n - I have a master degree in artificial intelligence and solving data\r\n problems\r\n with or without AI is my daily bread.\r\n - I also have a lot of interest and a bunch of experience in reinforcement\r\n learning, the field of AI most focused on automatically learning & solving\r\n games\r\n - I've been eyeing different turn-based games over the years, wondering,\r\n if you weren't trying to solve every game ever made, but a specific game,\r\n using the RL tools of today, would it be possible without renting a\r\n data center?\r\n - And I would love to explore this with my own games. However, if a proper\r\n game simulation engine would be developed (which follows naturally from\r\n programming games for playing them with rules), I can definitely see\r\n space for even general solutions, be it basic ones, for auto-balancing\r\n variables\r\n\r\n## Things I made with BGF\r\n\r\nSamples of prototypes I've made with this framework:\r\n\r\nhttps://imgur.com/a/TS779gR\r\n\r\n## Issues\r\n\r\nPlease report any issues and feel free to try and fix them on your own.\r\n\r\n## Contributors Welcome!\r\n\r\nI would love to welcome people on board who would like to extend the project\r\nor improve it. I believe we can build a community of people moving this project\r\nforward. I cannot achieve it myself, it's too much work for a free-time\r\nendeavor. As will be for you as well, but together we can meaningfully develop\r\nthis into something really, really useful to many more people.\r\n\r\nI see a big potential long-term. There are other tools that come close in what\r\nthey're trying to do, but I believe none of them is built with production-ready\r\nrendering capabilities.\r\n\r\nIf we go full crazy and draft some final vision, of what could be in a few\r\nyears:\r\n\r\n- earliest prototyping\r\n - just create a bunch of cards from a spreadsheet with auto-layout and move\r\n them around in a simulator to test your game basics\r\n- early prototyping\r\n - after first validation and adjustments, it's time to create prototype\r\n visuals, use GUI to build them, import the same data from the spreadsheet\r\n you already have, but this time put it where you want to put it\r\n - add basic icons (there will be a library of free ready-made assets just a\r\n click away)\r\n - do more simulation gameplay\r\n- first paper version\r\n - tweak visuals as needed\r\n - with a few clicks, export print sheets, or even better, print directly\r\n from\r\n the GUI itself, making sure DPI will match etc.\r\n- iterate, iterate, iterate\r\n - when you have a finalized version, start importing production-ready assets\r\n from designers and working on a beautiful, functional and clear layout\r\n - keep using the same spreadsheet from the start\r\n - (optional) - implement rules of your game into the game engine, allow\r\n other\r\n people to play it and give you feedback also online (multiplayer should\r\n definitely be added eventually)\r\n - as your assets get prettier and prettier, so does the simulated version of\r\n your game\r\n- everything is ready for production, sales, propagation\r\n - you export print sheets made to the specifications of devices of your\r\n printing contracts\r\n - all your production assets are automatically available to also play\r\n through\r\n the game engine.\r\n\r\nBut, one small step at a time. First things first, without community, I won't\r\ncome even close.\r\n\r\nI would love to hear your ideas and feature requests!\r\n\r\nIf you're interested you can drop in a PR directly, Issue with a\r\nfeature request or reach out to me at adam.volny at gmail dot com.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Board Game Factory - a framework for creating and scaling up production of vector graphics assets, e.g. for board games.",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/avolny/board-game-factory/issues",
"Homepage": "https://github.com/avolny/board-game-factory"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "624601c5d6f25c008f5f8a31fa040e45b00e94ca1254e22002ce2d6e4460db39",
"md5": "e89cbfb422543ccf44d2a92564a6b3f1",
"sha256": "d486794967ca61f191afe3644e6b7d5a08a26b7e387c900015eb6ec4446abfe7"
},
"downloads": -1,
"filename": "board_game_factory-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e89cbfb422543ccf44d2a92564a6b3f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 55033,
"upload_time": "2024-06-17T15:55:40",
"upload_time_iso_8601": "2024-06-17T15:55:40.706545Z",
"url": "https://files.pythonhosted.org/packages/62/46/01c5d6f25c008f5f8a31fa040e45b00e94ca1254e22002ce2d6e4460db39/board_game_factory-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0fe2055782eb93a9b05126f645e3231982db77b3fc4b8ff35512ebfce87b36ac",
"md5": "d7bc83323e096eb88953606c6a57be9e",
"sha256": "746736b13d72beba14f34abb5b16e60c37e8c1c249becd209de69ad678bc6e33"
},
"downloads": -1,
"filename": "board_game_factory-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d7bc83323e096eb88953606c6a57be9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 72540,
"upload_time": "2024-06-17T15:55:50",
"upload_time_iso_8601": "2024-06-17T15:55:50.344467Z",
"url": "https://files.pythonhosted.org/packages/0f/e2/055782eb93a9b05126f645e3231982db77b3fc4b8ff35512ebfce87b36ac/board_game_factory-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-17 15:55:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avolny",
"github_project": "board-game-factory",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "board-game-factory"
}
JSON
