{"id":25772188,"url":"https://github.com/bfrymire/four-souls-mpc-formatter","last_synced_at":"2025-09-10T16:42:29.695Z","repository":{"id":278827717,"uuid":"931841043","full_name":"bfrymire/four-souls-mpc-formatter","owner":"bfrymire","description":"A tool for streamlining the process of creating your MakePlayingCards order for Four Souls cards.","archived":false,"fork":false,"pushed_at":"2025-02-28T17:28:00.000Z","size":658,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-08T16:38:40.490Z","etag":null,"topics":["cards"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bfrymire.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-13T00:04:01.000Z","updated_at":"2025-05-07T18:31:29.000Z","dependencies_parsed_at":"2025-02-21T23:45:42.575Z","dependency_job_id":"a6c451a1-fed1-4699-8344-677e648fd967","html_url":"https://github.com/bfrymire/four-souls-mpc-formatter","commit_stats":null,"previous_names":["bfrymire/four-souls-mpc-formatter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bfrymire/four-souls-mpc-formatter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bfrymire%2Ffour-souls-mpc-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bfrymire%2Ffour-souls-mpc-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bfrymire%2Ffour-souls-mpc-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bfrymire%2Ffour-souls-mpc-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bfrymire","download_url":"https://codeload.github.com/bfrymire/four-souls-mpc-formatter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bfrymire%2Ffour-souls-mpc-formatter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274488063,"owners_count":25294650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cards"],"created_at":"2025-02-27T03:35:37.184Z","updated_at":"2025-09-10T16:42:29.681Z","avatar_url":"https://github.com/bfrymire.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/bfrymire/four-souls-mpc-formatter/master/assets/images/LOGO.png\" style=\"display:block; margin:auto; width:300px\" alt=\"Four Souls MPC Formatter Logo\"\u003e\u003c/div\u003e\r\n\u003ch1 align=\"center\"\u003eFour Souls MPC Formatter v1.0.0\u003c/h1\u003e\r\n\r\n**Four Souls MPC Formatter** is a program to format your locally downloaded, print-ready [Four Souls](https://foursouls.com) cards into XML files. These files are then fed into [mpc-autofill](https://github.com/chilli-axe/mpc-autofill) to ✨automagically✨ fill out your [_MakePlayingCards_](https://www.makeplayingcards.com/) order.\r\n\r\n### Standing on the Shoulders of Giants\r\n\r\n_mpc-autofill_ was originally designed for handling _Magic: The Gathering_ cards, but thanks to its powerful automation, we can use the same process to make printing _Four Souls_ cards just as easy.\r\n\r\n## Contents\r\n\r\n1. [Getting Started](#getting-started)\r\n2. [How to Format Card Directories](#how-to-format-card-directories)\r\n3. [How to Create Double-Sided Cards](#how-to-create-double-sided-cards)\r\n4. [FAQ](#faq)\r\n5. [Additional Questions](#additional-questions)\r\n6. [Attributions](#attributions)\r\n7. [Logo License](#logo-license)\r\n8. [License](#license)\r\n\r\n## Getting Started\r\n\r\nThis section provides an overview of how to set up and use _Four Souls MPC Formatter_. It will guide you through downloading the necessary programs, organizing your working directory, and adding your downloaded _Four Souls_ cards to directories. By following these steps, you'll be able to generate XML order files and use _mpc-autofill_ to prepare your cards for printing through _MakePlayingCards_.\r\n\r\nThis setup will guide you as though you're using the default directories and file names on a Windows OS.\r\n\r\n1. **Set Up a Working Directory**\r\n\r\n   - Create a new directory where you'll store your downloaded cards, necessary programs, config files, and output files in order to use _Four Souls MPC Formatter_.\r\n\r\n```\r\nmy-working-directory/\r\n```\r\n\r\n2. **Download _Four Souls MPC Formatter_ into your Working Directory**\r\n   - Download the [latest version](https://github.com/bfrymire/four-souls-mpc-formatter/releases/latest) from the Releases tab and place it in your working directory.\r\n\r\n```\r\nmy-working-directory/\r\n├── four-souls-mpc-formatter.exe\r\n```\r\n\r\n3. **Run _Four Souls MPC Formatter_ to Create Config File and Directories**\r\n\r\n   - Run the `four-souls-mpc-formatter.exe` program.\r\n     - The config file will be created automatically if it's missing.\r\n       - If you ever need to reset it, select the `Reset Config File to Default` option.\r\n     - Select the `Create Working Directories` option to create the directories.\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n│   ├── card_backs/\r\n│   ├── expansions/\r\n│   │   ├── Singles/\r\n├── orders/\r\n├── config.json\r\n├── four-souls-mpc-formatter.exe\r\n```\r\n\r\n4. **Download Standard Print-Ready _Four Souls_ Card Backs**\r\n\r\n   - The card back image files needed to print _Four Souls_ cards are not included here. They can be downloaded from the [Four Souls Templates Google Drive](https://drive.google.com/drive/u/0/folders/1b9iAG4i-SjnryKLiNMAKW8XFxeBt1Wjz).\r\n   - Once downloaded, move the card back image files into `cards/card_backs/`.\r\n   - The `four-souls-mpc-formatter.exe` program relies on the names in the `config.json` file to match up with the card back image files when generating the order files. These must match up either way, so you have two options:\r\n     1. Edit the `config.json` file to have the downloaded card back file names.\r\n     2. Rename the card back image files based on the default config file names.\r\n        - Make sure to preserve your file types when renaming the files. _(e.g., `.jpg`, `.png`)_\r\n\r\n**`config.json` Default Card Back File Names**\r\n\r\n| Card Type                      | File Name                   |\r\n| ------------------------------ | --------------------------- |\r\n| Bonus Soul                     | bonus_soul_card_back.jpg    |\r\n| Character                      | character_card_back.jpg     |\r\n| Loot                           | loot_card_back.jpg          |\r\n| Monster                        | monster_card_back.jpg       |\r\n| Room                           | room_card_back.jpg          |\r\n| Starting Item _(Eternal Item)_ | starting_item_card_back.jpg |\r\n| Treausre                       | treasure_card_back.jpg      |\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n│   ├── card_backs/\r\n│   │   ├── bonus_soul_card_back.jpg\r\n│   │   ├── character_card_back.jpg\r\n│   │   ├── ...\r\n│   ├── expansions/\r\n├── orders/\r\n```\r\n\r\n5. **Download _mpc-autofill_**\r\n   - Download the [latest version of _mpc-autofill_](https://github.com/chilli-axe/mpc-autofill/releases/latest).\r\n   - Place the `autofill-windows.exe` program in the `orders/` directory.\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n├── orders/\r\n│   ├── autofill-windows.exe\r\n```\r\n\r\n6. **Download Print-Ready _Four Souls_ Cards**\r\n   - Download your favorite print-ready _Four Souls_ cards and move them to `cards/expansions/` into their own directory.\r\n   - Organize cards within each expansion folder by card types _(e.g., `loot/`, `treasure/`)_ recognized by vanilla _Four Souls_. Follow the [How to Format Card Directories](#how-to-format-card-directories).\r\n   - For cards that have unique backs, follow [How to Create Double-Sided Cards](#how-to-create-double-sided-cards).\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n│   ├── card_backs/\r\n│   ├── expansions/\r\n│   │   ├── My Favorite Four Souls Cards/\r\n│   │   │   ├── loot/\r\n│   │   │   ├── treasure/\r\n│   │   │   ├── ...\r\n├── orders/\r\n```\r\n\r\n7. **Run _Four Souls MPC Formatter_**\r\n   - You should now be ready to run the formatter to create the order files.\r\n   - Run the `four-souls-mpc-formatter.exe` program.\r\n   - Select the `Generate MPC Order Files` option.\r\n   - After running the program, you should see your XML order files created in `orders/`.\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n├── orders/\r\n│   ├── autofill-windows.exe\r\n│   ├── order_Base_Card_Types_loot.xml\r\n│   ├── order_Base_Card_Types_treasure.xml\r\n│   ├── ...\r\n```\r\n\r\n8. **Run _mpc-autofill_**\r\n   - Run the _mpc-autofill_ `autofill-windows.exe` program from within the `orders/` directory, as it searches for XML files in the same location.\r\n   - Follow the on-screen prompts.\r\n     - ⚠️ **Important!** ⚠️ The color correction settings provided by [Print Four Souls](https://printfoursouls.com/) were specifically tested for _MakePlayingCards_. If you're using a different print service, results may vary. When choosing _\"Which site should the tool auto-fill your project into?\"_, make sure to select _MakePlayingCards_.\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n├── orders/\r\n│   ├── autofill-windows.exe\r\n│   ├── order_Base_Card_Types_loot.xml\r\n│   ├── order_Base_Card_Types_treasure.xml\r\n│   ├── ...\r\n```\r\n\r\n![mpc-autofill Terminal](https://raw.githubusercontent.com/bfrymire/four-souls-mpc-formatter/master/assets/images/mpc-autofill_terminal.png)\r\n\r\n9. **Review Your Order**\r\n\r\n   - Once _mpc-autofill_ has finished filling out the card fronts and backs, carefully review the **Preview \u0026 Add to Cart** step to ensure all cards are correctly formatted.\r\n\r\n10. **Update Your _MakePlayingCards_ Cart**\r\n\r\n- _mpc-autofill_ has default settings it selects on _MakePlayingCards_:\r\n  - **Card Stock:** _(M31) Linen_\r\n  - **Card Finishing:** _MPC game card finish_\r\n- Once the order is in your cart, update the **Card Finishing** setting.\r\n- Based on [Print Four Souls](https://printfoursouls.com//) recommendations, change **Card Finishing** to **BETA playing card finish**.\r\n\r\n![Print Four Souls Suggested Regular Card Settings](https://raw.githubusercontent.com/bfrymire/four-souls-mpc-formatter/master/assets/images/printfoursouls_mpc_settings.png)\r\n\r\n![MPC Change Card Finishing for Order in Cart](https://raw.githubusercontent.com/bfrymire/four-souls-mpc-formatter/master/assets/images/mpc_cart_change_card_finishing.png)\r\n\r\n11. **Complete Order!**\r\n\r\n- Now, finalize your _MakePlayingCards_ order. Happy printing!\r\n\r\n## How to Format Card Directories\r\n\r\nTo ensure that _Four Souls MPC Formatter_ correctly processes your cards, you need to organize them into specific directories based on their card type. The default card types recognized by vanilla _Four Souls_ are:\r\n\r\n- Bonus Soul\r\n- Character\r\n- Loot\r\n- Monster\r\n- Room\r\n- Starting Item _(also commonly referred to as Eternal Item)_\r\n- Treasure\r\n\r\nEach card type should be placed in its corresponding directory within an expansion folder. This ensures that the generated order files correctly group card types for printing.\r\n\r\n### Example Directory Structure\r\n\r\nWhen organizing your expansion, follow this structure:\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n│   ├── card_backs/\r\n│   ├── expansions/\r\n│   │   ├── My Favorite Four Souls Cards/\r\n│   │   │   ├── bonus_soul/\r\n│   │   │   ├── character/\r\n│   │   │   ├── loot/\r\n│   │   │   ├── monster/\r\n│   │   │   ├── room/\r\n│   │   │   ├── starting_item/\r\n│   │   │   ├── treasure/\r\n│   │   ...\r\n├── orders/\r\n```\r\n\r\nIn this example, the expansion _\"My Favorite Four Souls Cards\"_ contains seven subdirectories, each corresponding to a _Four Souls_ card type.\r\n\r\n### Notes on Formatting\r\n\r\n- **Folder names do not have to be case-sensitive**, `Starting Item/` and `starting_item/` will both be recognized as the same card type.\r\n- **Use \"Starting Item\" and not \"Eternal Item\"** when creating a card type folder for a character's initial item.\r\n- **Do not mix card types** within the same folder. Each card type must have its own folder.\r\n- **File names do not matter**, but using a consistent naming convention is recommended.\r\n- **Use unique file names** across all cards. _mpc-autofill_ may not properly fill out card slots that are using the same file name.\r\n- If an expansion **does not include** a certain card type, simply leave that folder out.\r\n\r\nFollowing this structure ensures that _Four Souls MPC Formatter_ can properly group and process your cards when generating order files.\r\n\r\nIf your card(s) need a custom card back, continue reading [How to Create Double-Sided Cards](#how-to-create-double-sided-cards).\r\n\r\n## How to Create Double-Sided Cards\r\n\r\nTo create double-sided cards, you need to group card fronts with their corresponding card back in a dedicated folder inside the `cards/expansions/Singles/` directory.\r\n\r\n### Steps:\r\n\r\n1. Inside `cards/expansions/Singles/`, create a **new folder** with a descriptive name for your set of double-sided cards.\r\n2. Place all **card front images** inside this folder. All cards in this folder will share the same card back.\r\n3. Inside this folder, create a `card_back/` directory.\r\n4. Place the **card back image** inside `card_back/`.\r\n\r\n### Example Directory Structure\r\n\r\n```\r\nmy-working-directory/\r\n├── cards/\r\n│   ├── card_backs/\r\n│   ├── expansions/\r\n│   │   ├── Singles/\r\n│   │   │   ├── Anima Sola/\r\n│   │   │   │   ├── card_back/\r\n│   │   │   │   │   ├── r-the_revenant.png\r\n│   │   │   ├── r-anima_sola.png\r\n```\r\n\r\n![Double-sided card example](https://raw.githubusercontent.com/bfrymire/four-souls-mpc-formatter/master/assets/images/double_sided_card_example.png)\r\n\r\n## FAQ\r\n\r\n##### **Q:** Does this color correct my _Four Souls_ cards?\r\n\r\n**A:** No, this tool is only for streamlining the process of creating your _MakePlayingCards_ order.  \r\nFor color correction, follow the method outlined on [Print Four Souls](https://printfoursouls.com/).\r\n\r\n##### **Q:** Where can I get print-ready card backs?\r\n\r\n**A:** You can download them from the [Four Souls Templates Google Drive](https://drive.google.com/drive/u/0/folders/1b9iAG4i-SjnryKLiNMAKW8XFxeBt1Wjz).\r\n\r\n##### **Q:** Will this work on macOS or Linux?\r\n\r\n**A:** Not at this time. Windows is the only supported OS.\r\n\r\n##### **Q:** I need help with mpc-autofill. Where should I go?\r\n\r\n**A:** Check out the [_mpc-autofill_ repository](https://github.com/chilli-axe/mpc-autofill) for further support and documentation. The _mpc-autofill_ tool we're using is the desktop-tool.\r\n\r\n##### **Q:** Can I use custom card backs?\r\n\r\n**A:** Yes! Place them in `cards/expansions/Singles/\u003cYour Expansion Name\u003e/card_back/`.  \r\nFor more details, check out [How to Create Double-Sided Cards](#how-to-create-double-sided-cards).\r\n\r\n## Additional Questions\r\n\r\nHave any questions? [Create a new issue!](https://github.com/bfrymire/four-souls-mpc-formatter/issues/new)\r\n\r\n## Attributions\r\n\r\nA huge thanks to the following projects and their contributors:\r\n\r\n- [Print Four Souls](https://printfoursouls.com/) for their work in refining a color-accurate method for printing _Four Souls_ cards.\r\n- [mpc-autofill](https://github.com/chilli-axe/mpc-autofill) for handling the automation of order filling, making the process seamless.\r\n\r\n## Logo License\r\n\r\nThe logo for the project has a separate [Logo License](./LICENSE_LOGO).\r\n\r\n## License\r\n\r\n[MIT License](./LICENSE)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbfrymire%2Ffour-souls-mpc-formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbfrymire%2Ffour-souls-mpc-formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbfrymire%2Ffour-souls-mpc-formatter/lists"}