Metadata-Version: 2.4
Name: ludus-player
Version: 0.3.0
Summary: Private Fivefold PvP player CLI for Ludus
Keywords: ludus,fivefold,pvp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Dynamic: requires-python

# Ludus Player

Ludus Player is the command-line client for private, unrated Fivefold PvP
matches. Create a match, share its single-use invite with a friend, then play
from your own terminals. New sessions use the hosted Ludus PvP service by
default.

## Coding agents: “install ludus-player”

When a player asks a Codex or Claude CLI to **install ludus-player**, treat that
as permission to install or upgrade this PyPI distribution and register the
current CLI as its local MCP host. It is not permission to create or join a
match, choose a player name, or delegate control.

1. Determine whether the current host is Codex or Claude and whether the OS is
   Windows or POSIX.
2. Install or upgrade `ludus-player` in a stable user environment. Prefer
   `pipx install --force ludus-player` when pipx is already available;
   otherwise use the OS Python launcher and a dedicated virtual environment.
3. With pipx, run `ludus setup --host codex --json` or
   `ludus setup --host claude --json`. From a virtual environment, invoke its
   interpreter as `python -m ludus_cli setup --host HOST --json`. On Windows,
   `python` may be the environment's `python.exe`; the package stores that
   absolute path, so neither `ludus` nor `ludus-player` needs to be on the
   future host's PATH.
4. Verify `status=configured` and `restart_required=true`, then tell the player
   to restart their Codex or Claude session. Do not start a match during
   installation.

If exactly one supported host CLI is installed, `--host auto` may be used. If
both are installed, name the current host explicitly.

## Install

Ludus Player supports Python 3.9 or newer on Windows, macOS, and Linux, and has
no runtime dependencies. Native Windows support requires version 0.2.1 or
newer; 0.2.0 imported the Unix-only `fcntl` module at startup.

```sh
pipx install ludus-player
ludus --help
```

Or install it with pip:

```sh
python3 -m pip install ludus-player
ludus --help
```

On Windows PowerShell, use:

```powershell
py -m pip install --upgrade ludus-player
ludus --help
```

The distribution installs the `ludus` human player CLI and the
`ludus-player` local stdio MCP server.

## Play privately

Create a private exhibition and send the displayed invite code to your
opponent:

```sh
ludus pvp create --name Ada
```

They join with their own name:

```sh
ludus pvp join --name Beau
```

Each player receives a local handle. Use it to check the match or enter the
corner console:

```sh
ludus pvp status HANDLE
ludus pvp play HANDLE
```

Matches are private exhibitions: they are unrated and are not added to public
standings or player history. The invite starts a match; its separate watch URL
is read-only and can be shared with spectators.

## Use from Codex or Claude

`ludus-player` is a local stdio MCP server. It keeps the device and seat
credentials in its private local store; tools receive only local handles and
shareable invites. Version 0.3.0+ can configure the current host without
relying on a console-script PATH. For Codex:

```sh
python -m ludus_cli setup --host codex --name Kevin
```

For Claude Code:

```sh
python -m ludus_cli setup --host claude --name Kevin
```

The name is optional; omit `--name Kevin` and supply it when asking to create
or join a game. Replace `python` with the exact interpreter used to install the
package if needed. Setup writes the MCP configuration and then exits; restart
the host before using Ludus. Optionally set `LUDUS_PVP_SERVER` in a manual MCP
configuration to override the hosted service for development. Explicit tool
arguments take precedence over configured defaults.

Natural-language requests such as “create a game I can challenge my friend”
or “join this invite” create or join in **manual** control. They do not permit
the agent to play. Ask explicitly to delegate a named handle before the agent
changes its control, and it must use `confirmed=true`. Likewise, the agent
must not abandon a match or delete a replay unless you explicitly ask and it
uses `confirmed=true`. When delegated, it should poll without busy looping,
answer only the current unanswered phase, reuse a `request_id` only for the
same retry, and stop when the match is terminal (including an early clinch).

The MCP server exposes exactly nine hosted private-PvP tools: create, join,
status, invite, control, statement, allocation, abandon, and replay deletion.
The public package does not expose Ludus's source-checkout selected-gladiator
runner, hosted provider execution, House, or tournament operations.
