Metadata-Version: 2.4
Name: ludus-player
Version: 0.2.1
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.

## 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. Register it with Codex:

```sh
codex mcp add ludus_player --env LUDUS_PLAYER_NAME=Kevin -- ludus-player
```

Or register it with Claude Code:

```sh
claude mcp add --transport stdio --scope user ludus_player \
  -e LUDUS_PLAYER_NAME=Kevin -- ludus-player
```

Replace `Kevin` with your player name. Optionally set `LUDUS_PVP_SERVER` to
override the hosted service for development. Explicit tool arguments take
precedence over either default.

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.
