Sil-Q terminal interface

Retrieve at least one Silmaril from Morgoth's crown and escape Angband carrying it. Each trial starts a fresh normal game. You can choose any race, house, stats, skills, and abilities. The manual recommends Noldor as the easiest race.

The game is pinned to Sil-Q v1.5.1-beta1. SILQ_MANUAL.txt is the text extracted from the upstream 1.5.0 manual bundled with this release. It explains combat, stealth, skills, experience, smithing and abilities. Some introductory passages describe original Sil: for example, this version starts with a curved sword. Use the screen and native item and ability descriptions when they differ from the manual.

These documentation corrections apply to this pinned version:

• Song of Elbereth consumes one Voice per turn while singing. The older manual's one-third-per-turn rate is incorrect for this version.
• Song of Mastery consumes two Voice per turn while singing. The older manual's one-per-turn rate is incorrect. Staunching costs one per turn, as the manual states.
• Strength in Adversity raises Strength, Dexterity and Grace: +1 at or below half health, and +3 at or below quarter health. The manual omits Dexterity. It does not raise Constitution.
• Territorial monsters may pursue a visible player. Their territorial rule stops pursuit when line of sight is lost; native recall omits that condition.

Commands and lifecycle

silq overall
silq start
silq state
silq press '6' --trial 1 --frame 1
silq press --json-keys '"\r"' --trial 1 --frame 2

Use the trial and frame from your latest response; the numbers above are examples. start consumes the next scheduled trial; it cannot reset a live game. state returns the current screen without sending native input or advancing the game. overall shows the schedule and recorded outcomes. finish voluntarily retires the live trial for zero. A completed schedule cannot be extended, and a finished game cannot be resumed. Continue through every trial.

press accepts 1–64 ASCII characters. Case matters. A single character returns the next input screen. For multiple characters, the service sends each one only after receiving the previous screen. The CLI saves every intermediate frame in /workspace/silq-history/trial-NN.jsonl and prints the last state with a history receipt listing the saved frame range. This keeps command output within the coding tool's limit. Inspect an earlier frame with silq history --trial N --frame F; this reads the local archive without sending any game input. History is also saved for single-key responses and screen reads. Keep these files if you want to analyze your earlier play.

The service stops a batch at the game's end or a resource limit. An unexpected prompt can change what the remaining keys mean. Use short batches when prompts or combat may interrupt an action. A stale frame, wrong trial or malformed request is rejected before sending a native key; fetch state to recover.

--json-keys decodes a JSON string. Useful escapes are "\r" (Enter), "\u001b" (Escape), "\t" (Tab), "\b" (Backspace), "\u007f" (Delete) and " " (Space). No shell escape syntax is interpreted inside an ordinary literal keys argument. The CLI saves each mutation before sending it and retries a lost response with the same request ID. Use silq retry to repeat the last saved request safely. A recovered batch may contain only its executed prefix; inspect its current state before sending more keys. Restarting the service does not reset a trial's deadline.

For programs, http://game:8080 accepts GET /state and GET /overall. Every POST /start, /act, or /finish requires a unique canonical UUID in request_id. Start also requires the next trial; act requires trial, frame, and keys; finish requires trial and frame. Retry the exact same body to retrieve its receipt. For example, an act body is {"request_id":"f09c8ede-a2c6-40ee-bd10-e8e3a456bb87","trial":1,"frame":2,"keys":"6"}. Generate a new UUID for each new action. Errors have an error field, and the CLI exits with status 2. Check for errors before choosing the next action. If local history saving fails after a request, the CLI reports history_save_failed_after_request and the final state; the keys may already have executed. Fetch the current state before deciding whether to send more keys. Local archives are for your analysis; the protected service records scores.

Programs using HTTP directly receive the complete frames array and final state for batches. Retain those frames yourself; printing a large raw batch can be truncated by the coding tool even when you request a large output allowance.

Reading the screen

Each response contains screen.rows: the native 80-column, 27-row terminal. Coordinates are zero-based. Trailing spaces are omitted; pad each row to 80 characters when building a grid. The screen shows the current panel. Menus can cover the map, the panel can scroll, and unseen terrain is not exposed. Use the native look, map and list commands to inspect what your character knows.

screen.attributes preserves colors as runs [row, column, length, attribute]. Unlisted cells have attribute 1 (white). An attribute's base color is its value modulo 16; the integer quotient by 16 is its native shade. Base colors are:

Color distinguishes map symbols and highlights menu choices and command letters. Preserve it when parsing the screen. cursor is [column,row]; cursor_visible reports whether the native terminal shows it. A hidden cursor's position can be stale. Screen coordinates are not persistent dungeon coordinates. bell_count records native warning beeps since the preceding frame. An invalid keypress may ring the bell while leaving the text unchanged. Re-reading the current state returns that same recorded frame; it does not ring a new bell.

The target sidebar's monster alertness label can lag a native state transition. Press [ for a freshly generated visible-monster list; Escape returns to the game. Use the list to check a potentially stale sidebar label.

The response also reports trial phase/status, keys used and wall time remaining. A native key can consume no game turn (a menu), one turn (movement), or many turns (running/resting/repeat commands). The next response arrives when the native game waits for input again. Native -more- prompts require input; they are not skipped. Inspect the resulting screen after dismissing them. The service has no automatic movement, pathfinding, combat policy, monster detector or item identification.

Native controls

The standard Sil-Q numerical keyset is fixed. In menus, 8 and 2 navigate up and down, 4 and 6 decrease/increase or move left/right, and Enter accepts the current selection. Read each prompt: letters often choose an item directly. During character creation you choose race, house, stats, skills, history, age/height/weight and name. Type a name and Enter. The introductory poem also waits for a key. Escape can return to earlier birth choices before the dungeon exists.

These keys apply at the gameplay prompt. In an inventory, target, direction, quantity, confirmation or menu prompt the same character may mean something else. Inventory and equipment lists allow follow-on item commands. Check the prompt and highlighted shortcuts before sending a key.

Scope of the evaluation

Wizard/debug/spoiler modes, configuration changes, native macros, custom preferences, file exports and native save/load are unavailable. Use scripts in your own workspace for automation and notes. Native gameplay rules and normal menus remain in the engine. A fixed September calendar avoids holiday items; dungeons, encounters, combat and unidentified item flavors remain randomized. Games cannot be reset, tutorials replayed, or the random schedule inspected.

The service scores the native ending and inventory. Escape with a Silmaril earns 1. Empty-handed escape, reaching 1000 ft without returning, death with a jewel, quit, retirement, or an unfinished game earns 0. Other progress is recorded for analysis. Names, inscriptions, workspace files, and your final report do not affect the score.