Skip to main content

"CLI, web API and Discord bot for VTES cards and TWDA.",

Project description

KRCG

PyPI version Validation Coverage Python version License Code Style

A web API and command-line interface based on the VEKN official card texts and the Tournament Winning Deck Archive (TWDA)

Portions of the materials are the copyrights and trademarks of Paradox Interactive AB, and are used with permission. All rights reserved. For more information please visit white-wolf.com.

Dark Pack

Online API

KRCG is available as an online API. Feel free to use it.

Discord BOT

KRCG is available as a Discord Bot. Feel free to use it in your server.

It lets you retrieve cards official text, image and rulings: Bot Example

Static Files

KRCG provides normalized static files for third parties, they can be found in the static folder:

  • amaranth-twda.json: The TWDA in JSON format for Amaranth (card IDs are Amaranth specific).
  • standard-rulings.json: The rulings in JSON format
  • twd.htm: A normalized version of the TWDA

The schemas for the JSON files can be found in the schemas folder.

Contribute

Feel free to submit pull requests, they will be merged as long as they pass the tests. Do not hestitate to submit issues or vote on them if you want a feature implemented.

Contribute Rulings (non-developers)

Please do not hestitate to contribute rulings: all help is welcome.

Open an issue with a ruling you think should be added, provide a link to an online post by one of the rules directors:

Contribute Rulings (developers)

Feel free to contribute rulings as Pull Requests directly, this is very appreciated.

Add the ruling link to rulings-links.yaml, and the ruling itself to cards-rulings.yaml or general-rulings.yaml depending on the case.

The format is mostly self-explanatory:

  • Cards are reference by ID and name in the format ID|Name.

  • Card names inside rulings text should be between bracers, eg. {.44 Magnum}

  • Individual rulings in cards-rulings.yaml must provide one or more references to ruling links at the end of the text, between brackets, eg [LSJ 20100101]

In doing so, please follow the following guidelines:

  • Keep the YAML files clean and alphabetically sorted (you can use a YAML formatter)

  • Make the rulings as concise as possible

  • Prefix the ruling with the discipline level and/or type the ruling applies to (if any), eg. prefix with [PRO] [COMBAT] if the ruling applies only to the card played in combat at superior Protean.

  • Adapt the ruling wording to the cards it applies to (ie. use masculine/feminin forms)

  • You can run the tests with the pytest command to check everything is OK

Installation

Python 3 is required.

Use pip to install the krcg tool:

pip install krcg

Using the library

KRCG is a Python library for VTES. The code is well-documented and can be explored using Python's built-in help function.

Here are a few quickstart examples to showcase how the library can be used:

>>> from krcg.vtes import VTES
>>> VTES.load_from_vekn()
>>> VTES.configure()
>>> VTES["Alastor"]
{'Id': '100038',
 'Name': 'Alastor',
 'Aka': '',
 'Type': ['Political Action'],
 'Clan': [],
 'Discipline': [],
 'Pool Cost': '',
 'Blood Cost': '',
 'Conviction Cost': '',
 'Burn Option': False,
 'Card Text': 'Requires a justicar or Inner Circle member.\nChoose a ready Camarilla vampire. If this referendum is successful, search your library for an equipment card and place this card and the equipment on the chosen vampire. Pay half the cost (round down) of the equipment. This vampire may enter combat with any vampire controlled by another Methuselah as a +1 stealth Ⓓ  action. This vampire cannot commit diablerie. A vampire may have only one Alastor.',
 'Flavor Text': '',
 'Set': ['Gehenna:R', 'KMW:PAl', 'KoT:R'],
 'Requirement': ['justicar', 'inner circle'],
 'Banned': '',
 'Artist': 'Monte Moore',
 'Capacity': '',
 'Draft': ''}
>>> VTES.rulings["Alastor"]
{'Rulings': ['If the given weapon costs blood, the target Alastor pays the cost. [LSJ 20040518]',
  'Requirements do not apply. [ANK 20200901]'],
 'Rulings Links': [{'Reference': 'LSJ 20040518',
   'URL': 'https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/4emymfUPwAM/B2SCC7L6kuMJ'},
  {'Reference': 'ANK 20200901',
   'URL': 'http://www.vekn.net/forum/rules-questions/78830-alastor-and-ankara-citadel#100653'}]}
>>> VTES.complete("pentex")
['Pentex™ Loves You!',
 'Pentex™ Subversion',
 'Enzo Giovanni, Pentex Board of Directors',
 'Enzo Giovanni, Pentex Board of Directors (ADV)',
 'Harold Zettler, Pentex Director']

Hosting the web API

To host the web API, you need to install the web version of krcg:

pip install "krcg[web]"

No wsgi server is installed by default, you need to install one. HTTP web servers can then easily be configured to serve WSGI applications, check the documentation of your web server.

The API can be served with uWSGI:

uwsgi --module krcg.wsgi:application

or Gunicorn:

gunicorn krcg.wsgi:application

Two environment variables are expected: GITHUB_USERNAME and GITHUB_TOKEN, to allow the API to connect to Github as a user in order to post new rulings as issues on the repository (/submit-ruling endpoint).

See the Github help on how to generate a personal token for the account you want KRCG to use.

Development

The development version of KRCG installs uWSGI to serve the API, this is the preferred WSGI server for now.

$ pip install -e ".[dev,web]"
$ make serve
...
uwsgi socket 0 bound to TCP address 127.0.0.1:8000

You can check the API is running by using your browser on the provided address http://127.0.0.1:8000.

The environment variables GITHUB_USERNAME and GITHUB_TOKEN can be provided by a personal .env file at the root of the krcg folder (ignored by git):

export GITHUB_USERNAME="dedicated_github_username_for_the_api"
export GITHUB_TOKEN="the_matching_github_token"

Hosting the bot

If you need to host a new version of the bot yourself, Python 3 is required, as well as an environment variable DISCORD_TOKEN. The token can be found on your Discord applications page.

The preferred way to run the bot is to use a python virtualenv:

/usr/bin/python3 -m venv venv
source venv/bin/activate
pip install krcg
DISCORD_TOKEN=discord_token_of_your_bot
krcg-bot

A systemd unit can be used to configure the bot as a system service:

[Unit]
Description=krcg-bot
After=network-online.target

[Service]
Type=simple
Restart=always
WorkingDirectory=directory_where_krcg_is_installed
Environment=DISCORD_TOKEN=discord_token_of_your_bot
ExecStart=/bin/bash -c 'source venv/bin/activate && krcg-bot'

[Install]
WantedBy=multi-user.target

For development, the environment variable DISCORD_TOKEN can be provided by a personal .env file at the root of the krcg folder (ignored by git):

export DISCORD_TOKEN="discord_token_of_your_bot"

Command line

An internet connection is required to initialize krcg with official VEKN data (cards list and TWDA).

krcg init

Use the help command for a full documentation of the tool:

krcg --help

And also extensive help on each sub-command:

krcg [COMMAND] --help

Note most commands only take decks from 2008 on in consideration. You can use the --from and --to parameters to control the date range.

Examples

Get a card text (case is not relevant, some abbreviations and minor misspellings will be understood):

$ krcg card krcg
KRCG News Radio
[Master][2P] -- (Jyhad:U, VTES:U, CE:U, LoB:PA, LotN:PG, KoT:U/PB, SP:PwN1 - #101067)
Unique location.
Lock to give a minion you control +1 intercept.
Lock and burn 1 pool to give a minion controlled by another Methuselah +1 intercept.

This provides rulings, if any:

$ krcg card ".44 magnum"
.44 Magnum
[Equipment][2P] -- (Jyhad:C, VTES:C, Sabbat:C, SW:PB, CE:PTo3, LoB:PO3, FB:PTr2 - #100001)
Weapon: gun.
Strike: 2R damage, with 1 optional maneuver each combat.

-- Rulings
Provides only ony maneuver each combat, even if the bearer changes. [LSJ 19980302-2]
The optional maneuver cannot be used if the strike cannot be used (eg. {Hidden Lurker}). [LSJ 20021028]

Use the -l option to get ruling links:

$ krcg card -l ".44 magnum"
.44 Magnum
[Equipment][2P] -- (Jyhad:C, VTES:C, Sabbat:C, SW:PB, CE:PTo3, LoB:PO3, FB:PTr2 - #100001)
Weapon: gun.
Strike: 2R damage, with 1 optional maneuver each combat.

-- Rulings
Provides only ony maneuver each combat, even if the bearer changes. [LSJ 19980302-2]
[LSJ 19980302-2]: https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/9YVFkeiL3Js/4UZXMyicluwJ
[LSJ 20021028]: https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/9YVFkeiL3Js/4UZXMyicluwJ

List TWDA decks containing a card:

$ krcg deck "Fame"
[2016gncbg] weenie animalism minimal: "Ich bin eine von wir"
[2016amfb] Gangrel e Garou
[2016ukncle] (No Name)
[2016ecday1gi] (No Name)
[2016saclcqspb] "Choquinho"
...

Display any TWDA deck:

$ krcg deck 2016gncbg
German NC 2016
Bochum, Germany
December 3rd 2016
3R+F
19 players
Bram van Stappen

Deck Name: weenie animalism minimal: "Ich bin eine von wir"
Description:
played (untested) at the German Nationals 03.12.2016, Bochum


-- Crypt: (12 cards)
---------------------------------------
2  Stick                               3  ANI                       Nosferatu antitribu:4
1  Janey Pickman                       6  for ANI PRO               Gangrel antitribu:4
1  Célèste Lamontagne                  5  for ANI PRO               Gangrel antitribu:4
1  Effie Lowery                        5  obf ANI SPI               Ahrimane:4
1  Sahana                              5  pre pro spi ANI           Ahrimane:4
1  Yuri Kerezenski                     5  aus for vic ANI           Tzimisce:4
1  Beetleman                           4  obf ANI                   Nosferatu:4
1  Bobby Lemon                         4  pro ANI                   Gangrel:3
1  Mouse                               2  ani                       Nosferatu:3
1  Zip                                 2  ani                       Ravnos:3
1  Lisa Noble                          1  ani                       Caitiff:3
-- Library (90)
-- Master (12)
5  Blood Doll
2  Powerbase: Montreal
1  Direct Intervention
1  Fame
1  KRCG News Radio
1  Pentex(TM) Subversion
1  Rack, The
-- Action (14)
10 Deep Song
2  Abbot
1  Aranthebes, The Immortal
1  Army of Rats
-- Combat (38)
16 Aid from Bats
11 Carrion Crows
6  Taste of Vitae
2  Canine Horde
2  Terror Frenzy
1  Pack Alpha
-- Reaction (18)
5  Cats' Guidance
5  On the Qui Vive
4  Forced Awakening
3  Delaying Tactics
1  Wake with Evening's Freshness
-- Equipment (1)
1  Sniper Rifle
-- Retainer (7)
6  Raven Spy
1  Mr. Winthrop

Display all decks that won a tournament of 50 players or more in 2018:

$ krcg deck --players 50 --from 2018 --to 2019
[2018igpadhs] (No Name)
[2018eclcqwp] Dear diary, today I feel like a wraith.. Liquidation
[2018ecday1wp] MMA.MPA (EC 2018)
[2018ecday2wp] EC 2018 win
[2018pncwp] Deadly kittens

List cards most associated with a given card in TWD:

$ krcg affinity "Fame"
Fame                           (in 100% of decks, typically 1-2 copies)
Taste of Vitae                 (in 59% of decks, typically 3-6 copies)
Dragonbound                    (in 38% of decks, typically 1 copy)
Powerbase: Montreal            (in 34% of decks, typically 1 copy)

List most played cards of a given type, clan or discipline:

$ krcg top -d animalism
Carrion Crows                  (played in 252 decks, typically 5-10 copies)
Cats' Guidance                 (played in 222 decks, typically 2-5 copies)
Canine Horde                   (played in 195 decks, typically 1-3 copies)
Deep Song                      (played in 194 decks, typically 3-10 copies)
Raven Spy                      (played in 182 decks, typically 2-6 copies)
Sense the Savage Way           (played in 167 decks, typically 2-6 copies)
Aid from Bats                  (played in 152 decks, typically 6-14 copies)
Army of Rats                   (played in 137 decks, typically 1-2 copies)
Guard Dogs                     (played in 83 decks, typically 1-3 copies)
Terror Frenzy                  (played in 73 decks, typically 1-4 copies)

Build a deck from any given cards based on TWDA:

$ krcg build "Fame" "Carrion Crows"

Created by: KRCG
Inspired by:
 - 2020mdmlf            Nanarch Buruku
 - 2019r6vh             Aksinya+Nana+Anarch+Ani 4.0
 - 2019bncfb            Resistência Anarch
 ...

-- Crypt: (12 cards)
---------------------------------------
1  Stick                               3  ANI                       Nosferatu antitribu:4
1  Beetleman                           4  obf ANI                   Nosferatu:4
1  Bobby Lemon                         4  pro ANI                   Gangrel:3
3  Nana Buruku                         8  ANI POT PRE               Guruhi:4
1  Céleste Lamontagne                  5  for ANI PRO               Gangrel antitribu:4
1  Petra                               5  aus ANI OBF               Nosferatu:4
4  Anarch Convert                      1  -none-                    Caitiff:ANY
-- Library (90)
-- Master (30)
8  Ashur Tablets
7  Anarch Revolt
3  Liquidation
3  Vessel
2  Dreams of the Sphinx
2  Haven Uncovered
1  Archon Investigation
1  Direct Intervention
1  Fame
1  Pentex(TM) Subversion
1  Wider View
-- Action (11)
10 Deep Song
1  Army of Rats
-- Combat (36)
13 Aid from Bats
10 Carrion Crows
4  Target Vitals
4  Taste of Vitae
3  Terror Frenzy
2  Canine Horde
-- Reaction (9)
4  Cats' Guidance
3  On the Qui Vive
2  Delaying Tactics
-- Retainer (4)
4  Raven Spy

Static files generator

In its development version, KRCG also offers a tool for generating static files for third parties, krcg-gen.

krcg init
krcg-gen standard amaranth

will generate files in the static folder for standard and amaranth third parties.

Some generated files are in JSON format, their schemas can be found in the schemas folder. The standard TWDA file is a rewrite of the original TWDA in the same HTML format.

Card images deployment

Provided the LackeyCCG plugin is up-to-date, the card images can be deployed on a distant server via a make command using rsync:

make sync-images

Project details


Release history Release notifications | RSS feed

This version

1.11

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

krcg-1.11.tar.gz (223.6 kB view hashes)

Uploaded Source

Built Distribution

krcg-1.11-py3-none-any.whl (255.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page