Metadata-Version: 2.4
Name: fyction_card_forge
Version: 0.0.5
Summary: A simple card generator library for original or custom TCG initial tests.
Author-email: Thiago Yure <thiagoyure.info@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Card-Generator

Card-Generator é uma biblioteca Python para gerar cartas de TCG (Trading Card Game) de forma aleatória e configurável. O projeto foi criado para apoiar testes de protótipos de jogos de cartas e sistemas que precisam gerar cartas com atributos dinâmicos a partir de templates definidos em JSON.

## Descrição do Projeto

A biblioteca oferece componentes modulares para:

- carregar configurações de templates e metadados a partir de arquivos JSON;
- gerar cartas com atributos aleatórios respeitando tipos, intervalos e listas de opções;
- validar cartas geradas de acordo com as regras do template;
- analisar cartas para calcular métricas como `power` com base em atributos e pesos;
- exportar o resultado para CSV para análise ou uso externo.

O projeto é organizado em uma estrutura clara de pacotes:

- `card_forge_fyction` - pacote principal da biblioteca;
- `core` - classes base de pipeline, contexto e exportação;
- `components` - gerador, validador, exportador CSV e analisador;
- `loaders` - carregador de configuração JSON;
- `models` - entidades `Card`, `Template` e `Configuration`;
- `exceptions` - exceções específicas para erros de carregamento, geração, validação e exportação.

## Quando usar

Use esta biblioteca quando precisar de um gerador de cartas TCG para:

- prototipar mecânicas de jogo;
- testar componentes de frontend ou backend que consomem cartas;
- gerar dados de teste para sistemas de balanceamento de cartas;
- criar inventários aleatórios de cartas.

## Como usar

### Instalação

A biblioteca está empacotada no repositório oficial PyPi: https://pypi.org/project/fyction-card-forge/

### Exemplo de uso

```python
from card_forge_fyction import CardForgeFyction

forge = CardForgeFyction("tests/assets/config/valid_config.json")
forge.generate()
cards = forge.get_cards()
for card in cards:
    print(card)

forge.export("cards_output")
```

### Passo a passo

1. Defina um arquivo JSON de configuração com:
   - `theme`, `description`, `metadata`;
   - `templates`, cada um com `name`, `quantity`, `attributes` e `rarities`.
2. Crie uma instância de `CardForgeFyction` passando o caminho do arquivo de configuração.
3. Chame `generate()` para gerar as cartas.
4. Use `get_cards()` para recuperar a lista gerada.
5. Chame `export(directory)` para salvar as cartas em CSV.

## Estrutura de configuração

A configuração básica do template deve incluir:

```json
{
  "name": "",
  "theme": "",
  "description": "",
  "templates": [
    {
      "name": "",
      "quantity": 0,
      "attributes": [
        {
          "name": "",
          "type": "",
          "min": 0,
          "max": 0,
          "options": [],
          "weight": 0
        }
      ],
      "rarities": []
    }
  ],
  "metadata": {
    "dictionary": []
  }
}
```

- `type` pode ser `int`, `str` ou `list`.
- `min` e `max` são usados para valores inteiros.
- `options` é usado para atributos do tipo `list`.
- `metadata.dictionary` é usado para gerar valores de `str`.

## Testes

O projeto inclui uma suíte de testes em `tests/` cobrindo:

- unidades de componentes e modelo;
- testes funcionais de geração e exportação;
- testes de integração para exportação CSV.

Execute os testes com:

```bash
python -m pytest -q
```

## Contribuindo

Se você quiser contribuir de alguma forma com esta biblioteca da sua maneira, copie o pacote `card_forge_fyction` para o seu repositório ou instale-o a partir do clone local. Adapte o JSON de configuração às regras de atributos e raridades do seu jogo.

---

Essa biblioteca fornece uma base para construção de um gerador de cartas TCG, e pode ser estendida com novas regras de raridade, tipos de atributo e mecanismos de balanceamento. Como essa é a versão inicial da biblioteca, atualizações e melhorias ainda podem acontecer com o tempo. Fiquem de olho!

