Complete API Reference
======================

This page lists every method available in the artifacts-mmo SDK. Both ``ArtifactsClient`` and ``AsyncArtifactsClient`` expose the same interface — async methods return coroutines instead of values.

Top-level Client Methods
-------------------------

The client provides access to game data and creates character controllers.

Server & Authentication
^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_status()``
     - —
     - Server status and version
   * - ``client.generate_token(username, password)``
     - ``str``, ``str``
     - Generate a JWT token

Account Management
^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.create_account(username, password, email)``
     - ``str``, ``str``, ``str``
     - Create a new account
   * - ``client.get_account(username)``
     - ``str``
     - Get public account info
   * - ``client.get_account_achievements(username)``
     - ``str``
     - Account achievements
   * - ``client.get_account_characters(username)``
     - ``str``
     - Characters on an account

Your Account
^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_my_details()``
     - —
     - Your account details
   * - ``client.get_bank()``
     - —
     - Your bank gold balance
   * - ``client.get_bank_items(page, size)``
     - optional
     - Items in your bank
   * - ``client.get_ge_orders(page, size)``
     - optional
     - Your active GE orders
   * - ``client.get_ge_history(page, size)``
     - optional
     - Your GE order history
   * - ``client.get_pending_items()``
     - —
     - Items waiting to claim
   * - ``client.get_my_characters()``
     - —
     - Your characters
   * - ``client.get_all_logs(page, size)``
     - optional
     - All action logs
   * - ``client.change_password(password, new_password)``
     - ``str``, ``str``
     - Change password

Character Management
^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.create_character(name, skin)``
     - ``str``, ``CharacterSkin``
     - Create a new character
   * - ``client.delete_character(name)``
     - ``str``
     - Delete a character
   * - ``client.get_all_characters(page, size)``
     - optional
     - All active characters
   * - ``client.get_character_data(name)``
     - ``str``
     - Get character info
   * - ``client.character(name)``
     - ``str``
     - **Create Character controller** →

Game Data Queries
^^^^^^^^^^^^^^^^^

**Items:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_item(code)``
     - ``str``
     - Get item by code
   * - ``client.get_all_items(...)``
     - ``min_level``, ``max_level``, ``type``, ``name``, ``page``, ``size``
     - List items with filters

**Monsters:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_monster(code)``
     - ``str``
     - Get monster by code
   * - ``client.get_all_monsters(...)``
     - ``min_level``, ``max_level``, ``page``, ``size``
     - List monsters

**Maps:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_all_maps(...)``
     - ``content_type``, ``content_code``, ``page``, ``size``
     - Find tiles by content
   * - ``client.get_maps_layer(layer, page, size)``
     - ``str``, optional
     - Tiles in a layer
   * - ``client.get_map(x, y)``
     - ``int``, ``int``
     - Get tile at coordinates
   * - ``client.get_map_by_id(id)``
     - ``int``
     - Get tile by ID

**Resources:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_resource(code)``
     - ``str``
     - Get resource by code
   * - ``client.get_all_resources(...)``
     - ``skill``, ``min_level``, ``max_level``, ``page``, ``size``
     - List resources

**NPCs:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_npc(code)``
     - ``str``
     - Get NPC by code
   * - ``client.get_all_npcs(page, size)``
     - optional
     - List all NPCs

**Events:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_all_active_events(page, size)``
     - optional
     - Currently active events
   * - ``client.get_all_events(page, size)``
     - optional
     - All events

**Other Data:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_achievement(code)``
     - ``str``
     - Get achievement
   * - ``client.get_all_achievements(...)``
     - ``type``, ``page``, ``size``
     - List achievements
   * - ``client.get_badge(code)``
     - ``str``
     - Get badge
   * - ``client.get_all_badges(page, size)``
     - optional
     - List badges
   * - ``client.get_effect(code)``
     - ``str``
     - Get effect
   * - ``client.get_all_effects(page, size)``
     - optional
     - List effects

**Grand Exchange (Read-only):**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_ge_item(code)``
     - ``str``
     - GE item data
   * - ``client.get_all_ge_items(page, size)``
     - optional
     - All GE items

**Leaderboard:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_leaderboard_characters(...)``
     - ``sort``, ``page``, ``size``
     - Character leaderboard
   * - ``client.get_leaderboard_accounts(...)``
     - ``sort``, ``page``, ``size``
     - Account leaderboard

**Tasks:**

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``client.get_task(code)``
     - ``str``
     - Get task definition
   * - ``client.get_all_tasks(...)``
     - ``type``, ``min_level``, ``max_level``, ``page``, ``size``
     - List tasks
   * - ``client.get_task_reward(code)``
     - ``str``
     - Get task reward
   * - ``client.get_all_task_rewards(page, size)``
     - optional
     - List task rewards

Character Controller Methods
-----------------------------

Create a character controller: ``char = client.character("name")``

Direct Character Actions
^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.get()``
     - —
     - Get current character state
   * - ``char.get_logs(page, size)``
     - optional
     - Character action log
   * - ``char.move(x, y)``
     - ``int``, ``int``
     - Move to coordinates
   * - ``char.fight()``
     - —
     - Fight monster at current location
   * - ``char.rest()``
     - —
     - Rest to recover HP
   * - ``char.transition()``
     - —
     - Enter/exit building
   * - ``char.claim_item(id)``
     - ``int``
     - Claim a pending item
   * - ``char.change_skin(skin)``
     - ``CharacterSkin``
     - Change character skin

Inventory
^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.use(code, quantity)``
     - ``str``, ``int``
     - Use a consumable
   * - ``char.delete_item(code, quantity)``
     - ``str``, ``int``
     - Delete items

Equipment
^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.equip(code, slot)``
     - ``str``, ``str``
     - Equip an item
   * - ``char.unequip(slot)``
     - ``str``
     - Unequip from slot

Skills (Craft/Gather)
^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.gather()``
     - —
     - Gather resource
   * - ``char.craft(code, quantity)``
     - ``str``, ``int``
     - Craft items
   * - ``char.recycle(code, quantity)``
     - ``str``, ``int``
     - Recycle equipment

Bank
^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.bank_deposit(code, quantity)``
     - ``str``, ``int``
     - Deposit items
   * - ``char.bank_withdraw(code, quantity)``
     - ``str``, ``int``
     - Withdraw items
   * - ``char.bank_deposit_gold(quantity)``
     - ``int``
     - Deposit gold
   * - ``char.bank_withdraw_gold(quantity)``
     - ``int``
     - Withdraw gold
   * - ``char.bank_buy_expansion()``
     - —
     - Buy +20 slots

Grand Exchange
^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.ge_sell(code, quantity, price)``
     - ``str``, ``int``, ``int``
     - Create sell order
   * - ``char.ge_buy(code, quantity, price)``
     - ``str``, ``int``, ``int``
     - Create buy order
   * - ``char.ge_cancel(id)``
     - ``str``
     - Cancel your order
   * - ``char.ge_get_orders()``
     - —
     - Get your active orders

Tasks & Quests
^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.task_new()``
     - —
     - Accept new task
   * - ``char.task_complete()``
     - —
     - Complete current task
   * - ``char.task_exchange()``
     - —
     - Exchange 6 coins for reward
   * - ``char.task_trade(code, quantity)``
     - ``str``, ``int``
     - Hand in task items
   * - ``char.task_cancel()``
     - —
     - Cancel task (costs 1 coin)

NPC Trading
^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.npc_buy(code, quantity)``
     - ``str``, ``int``
     - Buy from NPC
   * - ``char.npc_sell(code, quantity)``
     - ``str``, ``int``
     - Sell to NPC

Player Trading
^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Method
     - Parameters
     - Description
   * - ``char.give_gold(character, quantity)``
     - ``str``, ``int``
     - Give gold to player
   * - ``char.give_item(character, code, quantity)``
     - ``str``, ``str``, ``int``
     - Give item to player

Quick Examples
--------------

**Basic usage:**

.. code-block:: python

   from artifacts import ArtifactsClient
   
   client = ArtifactsClient(token="your_token")
   
   # Query game data
   item = client.get_item("iron_sword")
   monsters = client.get_all_monsters(max_level=10)
   
   # Control a character
   char = client.character("MyChar")
   char.move(x=1, y=2)
   char.gather()
   char.fight()

**Async usage:**

.. code-block:: python

   from artifacts import AsyncArtifactsClient
   import asyncio
   
   async def main():
       async with AsyncArtifactsClient(token="your_token") as client:
           char = client.character("MyChar")
           await char.move(x=1, y=2)
           await char.fight()
   
   asyncio.run(main())

See :doc:`examples/basic` for more examples.
