chuanqi/cq2_sdk/README.md

cq2_sdk

Python SDK for driving the cq2 (传奇) game through 13 new-player tasks via protocol-level simulation.

Architecture

3-layer (login / transport / task) + Lua bridge (lupa). Single-account synchronous async API.

Status

Pre-alpha. 996box authentication, detailed server resolution, TCP role login, and entry through SC2 world initialization are implemented. The 13 gameplay task classes remain protocol stubs.

Design documents

• Login spec: ../docs/superpowers/specs/2026-09-18-real-game-login-design.md
• Login plan: ../docs/superpowers/plans/2026-09-18-real-game-login.md

Installation

uv sync --group dev

Usage

from cq2_sdk import Cq2Client

async with Cq2Client(account="your-account", password="...") as cli:
    # Existing roles are selected automatically. If this zone has no role,
    # pass char_name="角色名", job=0, sex=0 explicitly.
    session = await cli.launcher.run_until_enter_game(zone_index=0)
    print(session.char_name, session.world_ready)

    # Gameplay tasks are still under protocol development.
    result = await cli.run_newbie_flow()
    print(f"完成 {len(result.completed_tasks)} 步, 用时 {result.elapsed}")

run_until_enter_game() returns only after the world server sends SC2. A live smoke run does not create a role unless char_name is supplied.

Development

cd cq2_sdk
uv sync
uv run pytest