Toolkit para desenvolvimento OTServ: converte, analisa, corrige e documenta scripts Lua e XML entre versões do TFS.

O TTT é um toolkit funcional com núcleo estável e algumas áreas em amadurecimento. A tabela abaixo reflete o estado real de cada módulo:

Legenda: Stable = testado e confiável · Beta = funcional, pode ter arestas · Experimental = requer dependência opcional, pode ter limitações · Stub = estrutura criada, sem lógica real

git clone https://github.com/zmovirzynski/TTT-Tibia-TFS-Transpiler.git
cd TTT-Tibia-TFS-Transpiler
python run.py --help

pip install -e .
ttt --help

git clone https://github.com/zmovirzynski/TTT-Tibia-TFS-Transpiler.git
cd TTT-Tibia-TFS-Transpiler
python -m venv .venv

# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .
pip install pytest>=7.0 ruff>=0.4.0

# Rodar a suite de testes
python -m pytest tests/ -v

Sobre o --use-ast: Quando luaparser não está instalado, features AST são desabilitadas silenciosamente. Sem a dependência, --use-ast no analyze não produz resultados de duplicatas semânticas. O conversor AST (ast_lua_transformer.py) faz fallback automático para o motor regex.

Limitações conhecidas do modo AST:

• Dependência externa (luaparser>=3.0)
• Pode falhar em scripts Lua com sintaxe não-padrão
• Duplicatas semânticas são experimentais — use como indicativo, não como verdade absoluta

python run.py

# Conversão completa TFS 0.3 → RevScript
ttt convert -i ./data/tfs03 -o ./output -f tfs03 -t revscript -v

# Dry-run (preview sem escrever arquivos)
ttt convert -i ./data/tfs03 -f tfs03 -t revscript --dry-run

# Com diff visual HTML
ttt convert -i ./data/tfs03 -o ./output -f tfs03 -t revscript --html-diff

ttt lint ./data/scripts
ttt lint ./data/scripts --format json
ttt lint --list-rules

ttt fix ./data/scripts --dry-run --diff
ttt fix ./data/scripts

ttt analyze ./data
ttt analyze ./data --format html --output analysis.html
ttt analyze ./data --only stats complexity storage

ttt doctor ./data
ttt doctor ./data --format json

ttt docs ./data --format html
ttt docs ./data --format markdown

ttt create --type action --name healing_potion --format revscript
ttt create --type creaturescript --name login --format tfs1x

ttt format ./data/scripts
ttt format ./data/scripts --check

O conversor marca pontos que precisam de revisão manual com comentários -- TTT: no código. Sempre revise esses marcadores antes de usar em produção.

function onUse(cid, item, frompos, item2, topos)
    if getPlayerLevel(cid) < 10 then
        doPlayerSendCancel(cid, "You need level 10.")
        return TRUE
    end
    doCreatureAddHealth(cid, 200)
    doSendMagicEffect(getCreaturePosition(cid), CONST_ME_MAGIC_BLUE)
    doRemoveItem(item.uid, 1)
    return TRUE
end

local healing_potion = Action()

function healing_potion.onUse(player, item, fromPosition, target, toPosition, isHotkey)
    if player:getLevel() < 10 then
        player:sendCancelMessage("You need level 10.")
        return true
    end
    player:addHealth(200)
    player:getPosition():sendMagicEffect(CONST_ME_MAGIC_BLUE)
    Item(item.uid):remove(1)
    return true
end

healing_potion:id(2274)
healing_potion:register()

function onLogin(cid)
    local name = getCreatureName(cid)
    doPlayerSendTextMessage(cid, MESSAGE_STATUS_DEFAULT, "Welcome, " .. name .. "!")
    registerCreatureEvent(cid, "PlayerDeath")
    doPlayerSetStorageValue(cid, 50000, 1)
    return TRUE
end

local login = CreatureEvent("PlayerLogin")

function login.onLogin(player)
    local name = player:getName()
    player:sendTextMessage(MESSAGE_STATUS_DEFAULT, "Welcome, " .. name .. "!")
    player:registerEvent("PlayerDeath")
    player:setStorageValue(50000, 1)
    return true
end

login:register()

[convert]
from = "tfs03"
to = "revscript"
input = "/path/to/scripts/"
output = "/path/to/output/"
dry_run = false
html_diff = true

[lint]
format = "text"

[analyze]
only = []
format = "text"
use_ast = false

[fix]
dry_run = true
backup = true

[doctor]
format = "text"

Prioridade: CLI > config.toml > defaults.

O comando ttt test é um runner de testes para scripts OTServ baseado em unittest, com mocks da API TFS (mockPlayer, mockCreature, mockItem, mockPosition) e asserts customizados.

Escopo: ttt test é voltado para testar scripts de servidor, não para rodar a suite interna do TTT.

Para rodar os testes do próprio TTT:

python -m pytest tests/ -v

ttt/
├── main.py                    # CLI principal
├── engine.py                  # Orquestrador de conversão
├── scanner.py                 # Scanner de diretórios
├── report.py                  # Relatórios de conversão
├── diff_html.py               # Diff visual HTML
├── mappings/                  # Tabelas de mapeamento
│   ├── tfs03_functions.py     # 217 mapeamentos TFS 0.3 → 1.x
│   ├── tfs04_functions.py     # 230+ mapeamentos TFS 0.4 → 1.x
│   ├── constants.py           # 243 constantes
│   ├── signatures.py          # 23 assinaturas de callback
│   └── xml_events.py         # Definições XML → RevScript
├── converters/                # Motores de conversão
│   ├── lua_transformer.py     # Transformador regex (principal)
│   ├── ast_lua_transformer.py # Transformador AST (experimental, requer luaparser)
│   ├── xml_to_revscript.py    # XML+Lua → RevScript
│   └── npc_converter.py       # Scripts NPC
├── linter/                    # Análise estática
├── fixer/                     # Correção automática
├── analyzer/                  # Análise de servidor (6 módulos)
├── doctor/                    # Diagnóstico de saúde
├── docs/                      # Geração de documentação
├── generator/                 # Scaffolding de scripts
├── formatter/                 # Formatação Lua
└── testing/                   # Framework de testes OTServ (beta)

vscode-extension/              # Extensão VS Code (beta)
tests/                         # Suite de testes (pytest)
examples/                      # Scripts de exemplo TFS 0.3

# Todos os testes (295 passing, 27 skipped)
python -m pytest tests/ -v

# Por módulo
python -m pytest tests/test_ttt.py -v        # Conversor
python -m pytest tests/test_linter.py -v     # Linter
python -m pytest tests/test_fixer.py -v      # Fixer
python -m pytest tests/test_analyzer.py -v   # Analyzer
python -m pytest tests/test_doctor.py -v     # Doctor
python -m pytest tests/test_formatter.py -v  # Formatter

Testes AST (test_ast_*.py) são automaticamente pulados quando luaparser não está instalado.

1. Clone e instale dependências de dev (veja instalação)
2. Rode os testes: python -m pytest tests/ -v
3. Garanta lint limpo: ruff check ttt/ tests/
4. Abra uma issue ou envie um PR

Para adicionar novos mapeamentos de funções, edite ttt/mappings/tfs03_functions.py ou tfs04_functions.py.

MIT