jarvis-yu/dottore-genius-invokation-tcg-simulator

A highly customizable Genius Invokation TCG simulator for Reinforcement Learning. (PyPI package: dgisim)

Dottore Genius Invokation TCG Simulator

A Genshin Impact Genius Invokation TCG simulator intended to be used for Reinforcement Learning.

• Documentation
• Source code
• Contributing
• Game design
• Bug reports
• Discord server
• QQ Group

This package aims to help programmers code things based on Genius Invokation TCG with ease. e.g. AI, desktop application, website...

The simulator is modeled as a finite state machine, where all game states are immutable. Optimizations are done to make sure immutability doesn't impact performance.

Basic rules of Genius Invokation TCG can be found on Fandom.

Installation

Please make sure your Python version >= 3.10 before installing.

pip install dgisim

RL Environment Usage Example

from dgisim import LinearEnv

env = LinearEnv()
rl_net = ...  # your RL network

for episode in range(100):
    env.reset()
    game_state, encoded_state, reward, turn, done = env.view()

    while not done:
        ...  # do the training on the encoded_state
        game_state, encoded_state, reward, turn, done = env.step(action)

For more details please check the documentation.

Try the Simulator in Browser

• Website: https://jarvis-yu.github.io/Dottore-Genius-Invokation-TCG-PWA/
• Repo: https://github.com/Jarvis-Yu/Dottore-Genius-Invokation-TCG-PWA

Try the Simulator in CLI

Run Locally

Once installed, you may start by trying the CLI to play the game first.

You might want to run a simple python program like this:

from dgisim import CLISession

session = CLISession()
session.run()

Run Remotely

You may try the CLI online on Google Colab

CLI Simple Usages

See CLI's tutorial for showcase and explanations of the CLI.

Features

The package allows:

• Customization of player agents
• Customization of characters
• Customization of cards
• Customization of game modes

This simulator is modeled as a finite state machine, which means any intermediate state can be standalone and be used to proceed to other states.

The GameState class represents some game state in the state machine. It uses passed in Phase object to determine how to transform to another state, which means the game flow is highly customizable. (Default Mode and some Heated Battle Modes are implemented already)

Everything in the GameState object are immutable, so traversing game history and exploring different branches of possibilities in the future are not error-prone. stable simulator did optimizations for immutability. The unchanged data are shared among neighbouring game states.

GameState implements __eq__ and __hash__, enabling you to use any game state as a key in a dictionary, and discover game states on different 'game branches' being actually the same.

An ActionGenerator can be returned by any valid GameState to help generate valid player actions.

Development Milestones

Currently a full game can be played with any combination of the characters and cards implemented.

• Implement all game phases (Action Phase, End Phase...)
• Implement all cards (169/283 implemented) (latest-details) (stable-details)
• Implement all characters with their talent cards (44/83 implemented) (latest-details) (stable-details)
• Implement all reactions, death handling, revival handling etc.
• Implement all game logics to support the implemented cards and characters
• Implement interactive CLI for better debugging experience
• Ensure 99% unittest coverage checking behaviour of characters and cards
• Implement lazy player agent for minimal testing purposes
• Implement random player agent for testing purposes
• Implement player action validity checker
• Implement player action choices provider

Future Plans

I have the plan to implement a simple cross-platform GUI interface for the simulator. But that will be in a separate repo.

Once this project is done, I'll be reading relative papers and develop an AI for this game. The AI is supposed to be used for learning strategies and making decks, but not against another player directly.

dottore-genius-invokation-tcg-simulator's Issues

Ganyu's Frostflake Arrow is not treated as normal attack

Add Optional to EncodingPlan.

Thanks for your great work. I tested the performance of env.view(), but it costed approximately 1.2ms

%timeit game_state, encoded_state, reward, turn, done = env.view()

I modified the env.view() method to enforce it return a None encoded_state, the speed was significantly improved to 30us.

I deem this option necessary, since user might want to encode the states later, after collecting adequate data. A use case is offline RL. We will use many expert agents to collect data at first and post-process collected data for training.

Supplementary:

And here is profile result for env.step():

It seems encoding costed most of the time. Disabling encoding would accelerate the data collection process significantly.

The Current Dice Reduction Mechanism in the Simulator Does Not Match the Actual Gameplay.

Expected tags: Medium-priority, Bug, Easy

Faulty Behaviour When Reroll Chance Is 0 By Default

If dices reroll chances for roll phase is set to 0 in mode, players can still roll once

The Existing "State > Combat State" Logic May Not Fully Correspond to Actual Game Behavior.

This might be one of the basic logics of the mechanism.

Create detailed milestone files and link them in README

There needs to be some milestone files containing the progress on cards and characters.

You should probably create the path readme/milestones/

Create two markdown files "cards_milestone.md" and "characters_milestone.md", each containing the progress on each character/card using a similar style as in "README.md" milestones section.

Refer to https://genshin-impact.fandom.com/wiki/Genius_Invokation_TCG/Card_List to find the list of all available cards. (note that we only want to implement cards obtainable by players for now)

If you have any questions regarding on the actual progress of the cards/characters, contact Jarvis-Yu, the repo owner.

Check wiki for code/commit style guide.

Support area is not implemented

Try to implement the supports area of the game.

Beware that there can be a number of the exact same type of support cards in this area.

A limit of 4 support cards in the area is not required for now, but leave a # TODO: message where appropriate in the codebase.

I recommend to implement the support cards Paimon and Favonius Cathedral to test the new support area.

Note that the support area should be immutable, and two support area objects containing same support cards in the same order and states should be equal to each other. (hash should be the same as well)

Write unit tests.

Calx's Arts - the event card is not implemented

Don't forget to write unit tests.

Related files:

• dgisim/src/card/card.py
• dgisim/tests/test_cards/test_calxs_arts.py (needs to be created)

For this issue, you just need to make use of what that is available, requiring you to understand relative code and assemble them. All required functionalities are already implemented.

Check wiki for code/commit style guide.

Implement & Unittest Tighnari

The Logic of the POST_DMG Signal Does Not Accurately Reflect the Actual Game Behavior

Bennett's "Inspiration Field" In The Simulator Does Not Match Its Performance In Actual Gameplay

Bennett's Inspiration Field healing effect targets the character who used the skill, not the currently active character.

This means if the active character is switched before Inspiration Field takes effect, such as using the elemental skill of Kazuha or the card Wind and Freedom, it will still heal the character who used the skill, rather than the new active character.

translate Shell scripts to Powershell scripts needed

Currently, in the scripts/ folder, there are some .sh scripts for shell, and some .ps1 scripts for powershell.

Unfortunately, the .ps1 scripts are out-dated, but the .sh ones are up-to-date.

Please translate cli.sh, test.sh, venv.sh, profile.sh and build.sh to corresponding .ps1 files. If there existed .ps1 file with the same name, overwrite them.

Don't be afraid, all scripts are very short, with just a few lines.

Once scripts are written, please try run them yourself before creating a Pull Request.

(Optionally, you may move all .sh scripts to scripts/sh/ and .ps1 scripts to scripts/ps1/)

Update event card I Haven't Lost Yet! according to game version 4.0

Limit usages to once per round

Inline-Import is Significantly Slower, Refactor to Remove most Inline-Imports

Tested with Python3.10, fb() is 4 times slower than fa()

def simple_function():
    if random.random() < 0.5:
        return 1
    else:
        return 0

def fa():
    return simple_function()

def fb():
    from module import function
    return simple_function()

ChangingShifts & LeaveItToMe should not be usable when only one character alive

But they are currently usable in the simulator.

Starsigns - the event card is not implemented

Don't forget to write unit tests.

Related files:

• dgisim/src/card/card.py
• dgisim/tests/test_card.py

How to deal with death?

100% Unittest Coverage

TriggeringSignal.COMBAT_ACTION Should be Splitted to Better Simulate Game Mechanics

Tests were performed showing cards like Absorbing Prism cannot trigger status effects that are described as "After Your Character uses a Skill".

Implement all Elemental die cards

Namely

• Elemental Resonance: Woven Flames
• Elemental Resonance: Woven Ice
• Elemental Resonance: Woven Stone
• Elemental Resonance: Woven Thunder
• Elemental Resonance: Woven Water
• Elemental Resonance: Woven Weeds
• Elemental Resonance: Woven Winds

Note that you don't need to implement the part relating to the precondition for it to be included in the deck, just implement the behaviour when it is played.

For this issue, you just need to make use of what that is available, requiring you to understand relative code and assemble them. All required functionalities are already implemented.

Check wiki for code/commit style guide.

Implement a smart dice selection algorithm

Currently there's a dice selection algorithm in dgisim/src/dices.py, the function name is basically_satisfy(). This algorithm is not smart enough to make the best choice on which dices to pay for a card or an action. It should be improved for the better.

If you are not familiar with the rules of Genius Invokation TCG, then please leave a comment below, otherwise you should know how in Genshin the dices are automatically selected for you when you want to do something.

As the current character class doesn't have info on the element type of the character, you cannot directly access it from the game_state, instead you should assume you can access that information and build the algorithm on that basis. So when in the future the information is accessible, the algorithm can adapt to the new character system immediately.

Check wiki for code/commit style guide.

Faulty charged attack judgement when triggered by talent equipment card

No card has precondition of usage defined, implement it

Each card should have a precondition which should be checked before the game_state proceed with the usage of this card.

Ideally the precondition takes the game_state and card_instruction, returning a boolean indicating if the usage is legal.

If the game_state cannot proceed because the precondition is not satisfied, return None or raise Exception. (return None is better)

Card Redrawing Should Try Avoid Pulling Same Cards As Discarded

As the title suggests, this is a bug that needs to be fixed.