Combat Simulation

The SDK includes a combat simulator that lets you test fight outcomes without actually fighting. This is useful for planning your equipment and strategy.

Warning

The simulation API requires a member/founder account.

How It Works

You create “fake” characters with specific equipment, then simulate fights against a monster. The simulator runs multiple iterations and gives you win/loss statistics.

Basic Simulation

from artifacts.models.combat import FakeCharacterSchema

# Create a simulated character
fake_char = FakeCharacterSchema(
    level=15,
    weapon_slot="iron_sword",
    helmet_slot="iron_helmet",
    body_armor_slot="iron_armor",
    boots_slot="iron_boots",
)

# Simulate 100 fights against a wolf
result = client.simulation.fight(
    characters=[fake_char],
    monster="wolf",
    iterations=100,
)

print(f"Wins: {result.wins}/{result.wins + result.losses}")
print(f"Win rate: {result.winrate:.1%}")

Testing Different Builds

from artifacts.models.combat import FakeCharacterSchema

# Build A: Heavy armor
tank_build = FakeCharacterSchema(
    level=20,
    weapon_slot="iron_sword",
    shield_slot="iron_shield",
    helmet_slot="iron_helmet",
    body_armor_slot="iron_armor",
    leg_armor_slot="iron_legs",
    boots_slot="iron_boots",
)

# Build B: Glass cannon
dps_build = FakeCharacterSchema(
    level=20,
    weapon_slot="steel_sword",
    ring1_slot="copper_ring",
    ring2_slot="copper_ring",
    amulet_slot="copper_amulet",
)

# Test both against the same monster
for name, build in [("Tank", tank_build), ("DPS", dps_build)]:
    result = client.simulation.fight(
        characters=[build],
        monster="ogre",
        iterations=200,
    )
    print(f"{name}: {result.winrate:.1%} winrate ({result.wins}W/{result.losses}L)")

Multi-Character Boss Simulation

You can simulate boss fights with multiple characters:

from artifacts.models.combat import FakeCharacterSchema

chars = [
    FakeCharacterSchema(level=25, weapon_slot="steel_sword", body_armor_slot="steel_armor"),
    FakeCharacterSchema(level=25, weapon_slot="steel_sword", body_armor_slot="steel_armor"),
    FakeCharacterSchema(level=25, weapon_slot="steel_sword", body_armor_slot="steel_armor"),
]

result = client.simulation.fight(
    characters=chars,
    monster="dragon_boss",
    iterations=50,
)

print(f"Win rate: {result.winrate:.1%}")
print(f"Results: {result.wins}W / {result.losses}L")

# View individual fight details
for i, fight in enumerate(result.results[:5]):
    print(f"  Fight {i+1}: {fight.result.value} in {fight.turns} turns")

FakeCharacterSchema Slots

When building a fake character, you can set any equipment slot:

Parameter	Description
level	Character level (required)
weapon_slot	Weapon item code
shield_slot	Shield item code
helmet_slot	Helmet item code
body_armor_slot	Chestplate item code
leg_armor_slot	Leggings item code
boots_slot	Boots item code
ring1_slot	First ring item code
ring2_slot	Second ring item code
amulet_slot	Amulet item code
artifact1_slot	Artifact slot 1
artifact2_slot	Artifact slot 2
artifact3_slot	Artifact slot 3
rune_slot	Rune item code
utility1_slot	Utility item 1
utility2_slot	Utility item 2

All slot parameters are optional — just set the ones you want to test.

Tip

Use client.items.get("item_code") to verify an item exists and check its stats before simulating.