Character

The Character object is a controller for a specific character in your account.

Purpose:

  • Control one character’s actions

  • Direct access to movement and combat

  • Access to domain-organized features (bank, crafting, trading, etc.)

Create a Character controller:

# From a client
client = ArtifactsClient(token="your_token")
char = client.character("MyCharacterName")

Getting Your Character

Each Character controller is tied to one character name:

from artifacts import ArtifactsClient

with ArtifactsClient(token="your_token") as client:
    # Create controllers for different characters
    fighter = client.character("Fighter")
    mage = client.character("Mage")
    crafter = client.character("Crafter")

    # Each operates independently
    fighter.move(x=0, y=1)
    mage.move(x=2, y=3)

Direct Actions

The Character provides direct methods for common actions:

Movement:

# Move to coordinates
response = char.move(x=1, y=2)

# Check new position
print(f"Now at: ({response.data.x}, {response.data.y})")

Combat:

# Fight a monster at current location
result = char.fight()
print(f"Result: {result.fight.result}")
print(f"XP gained: {result.fight.xp}")

Rest & Recovery:

# Rest to recover HP (must be at spawn point)
result = char.rest()
print(f"HP: {result.data.hp}/{result.data.max_hp}")

Get Character Data:

# Get full character info
data = char.get()

print(f"Name: {data.name}")
print(f"Level: {data.level}")
print(f"Position: ({data.x}, {data.y})")
print(f"HP: {data.hp}/{data.max_hp}")

# Check inventory
for slot in data.inventory:
    if slot.code:
        print(f"  {slot.quantity}x {slot.code}")

Domain Objects

For organized feature access, Character groups related methods:

char.bank       # Bank operations (deposit, withdraw)
char.equipment  # Equip/unequip items
char.skills     # Crafting, gathering, recycling
char.ge         # Grand Exchange trading
char.inventory  # Inventory management
char.tasks      # Quest management
char.trading    # Player-to-player trading

These are just attributes of the Character that group related methods together.

See Character Feature Groups for detailed documentation of each group.

Example using grouped methods:

# Crafting (via char.skills)
char.skills.craft(code="iron_sword", quantity=1)

# Banking (via char.bank)
char.bank.deposit_gold(quantity=100)

# Trading (via char.ge)
char.ge.sell(code="copper_ore", quantity=10, price=50)

Character Class Reference

class artifacts.Character[source]

Bases: object

Controller for a single character.

Created via client.character("name"). Actions are organized into game-oriented sub-objects:

char = client.character("MyChar")

# Direct actions (combat & movement)
await char.move(x=0, y=1)
await char.fight()
await char.rest()

# Domain sub-objects
await char.skills.craft(code="iron_sword")
await char.bank.deposit_gold(quantity=100)
await char.equipment.equip(code="iron_sword", slot=ItemSlot.WEAPON)
await char.inventory.use(code="cooked_chicken")
await char.tasks.new()
await char.ge.sell(code="iron_ore", quantity=10, price=5)
await char.trading.npc_buy(code="healing_potion")

By default, the SDK automatically waits for cooldowns before each action so that results are returned immediately. Override per-call with wait=False:

result = await char.fight(wait=False)  # returns immediately
__init__(name, http, *, auto_wait=True)[source]
Parameters:

  • name (str)

  • http (HttpClient)

  • auto_wait (bool | list)

async get()[source]

Fetch full character info (GET /characters/{name}).

Return type:

CharacterSchema

async get_logs(*, page=1, size=50)[source]

Fetch character action history (GET /my/logs/{name}).

Return type:

DataPage[LogSchema]

Parameters:

  • page (int)

  • size (int)

async move(*, x=None, y=None, map_id=None)[source]

Move the character.

Provide either map_id or x + y coordinates.

Return type:

CharacterMovementDataSchema

Parameters:

  • x (int | None)

  • y (int | None)

  • map_id (int | None)

async transition()[source]

Execute a layer transition (go underground, enter building, etc.).

Return type:

CharacterTransitionDataSchema

async fight(*, participants=None)[source]

Fight a monster on the current map tile.

For bosses, pass up to 2 additional character names in participants.

Return type:

CharacterFightDataSchema

Parameters:

participants (list[str] | None)

async rest()[source]

Rest to recover HP.

Return type:

CharacterRestDataSchema

async claim_item(id)[source]

Claim a pending item.

Return type:

ClaimPendingItemDataSchema

Parameters:

id (int)

async change_skin(*, skin)[source]

Change character skin.

Return type:

ChangeSkinCharacterDataSchema

Parameters:

skin (CharacterSkin)

Common Patterns

Context Manager (Recommended):

with ArtifactsClient(token="your_token") as client:
    char = client.character("MyChar")
    char.move(x=1, y=2)
    # Automatic cleanup

Multiple Characters:

with ArtifactsClient(token="your_token") as client:
    gatherer = client.character("Gatherer")
    crafter = client.character("Crafter")

    # Gatherer collects resources
    gatherer.move(x=2, y=0)
    gatherer.skills.gather()

    # Transfer via bank
    gatherer.move(x=4, y=1)
    gatherer.bank.deposit_items(items=[...])

    # Crafter picks up and crafts
    crafter.move(x=4, y=1)
    crafter.bank.withdraw_items(items=[...])
    crafter.move(x=1, y=1)
    crafter.skills.craft(code="iron_sword")

Async Multiple Characters:

async def fight_loop(char, count):
    for i in range(count):
        result = await char.fight()
        print(f"{char._name}: {result.fight.result}")
        await asyncio.sleep(result.data.cooldown)

async def main():
    async with AsyncArtifactsClient(token="your_token") as client:
        fighters = [
            client.character("Fighter1"),
            client.character("Fighter2"),
            client.character("Fighter3")
        ]

        # All fight in parallel
        await asyncio.gather(*[fight_loop(f, 10) for f in fighters])

asyncio.run(main())

See Also