Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Copilot Instructions for Jericho

Jericho is a Python library that connects learning agents with interactive
fiction (text adventure) games via a Z-machine interpreter (frotz).

## Building the Project

```bash
pip install -e '.'
```

This compiles the frotz C library and installs jericho in development mode.
Run tests with `pytest -vv tests/`.

## Game ROMs

Game ROM files (`.z3`, `.z5`, `.z8`, etc.) live in the `roms/` directory.

To download games from the canonical game suite:

```bash
# Download a specific game
curl -fsSL "https://raw.githubusercontent.com/BYU-PCCL/z-machine-games/master/jericho-game-suite/<game>.z5" -o roms/<game>.z5

# Browse the full suite at:
# https://github.com/BYU-PCCL/z-machine-games/tree/master/jericho-game-suite
```

## External Resources

### IFDB — Interactive Fiction Database

Use https://ifdb.org/ to look up game metadata, descriptions, ratings, and
details. Useful API patterns:

- Search for a game: `https://ifdb.org/search?searchfor=<game+name>`
- View a game page: `https://ifdb.org/viewgame?ifid=<IFID>`

### Transcripts — allthingsjacq.com

Game transcripts and walkthroughs are available at https://allthingsjacq.com/.
Use these to understand expected game behavior, solutions, and interaction
patterns.

### Walkthroughs (local)

This repository does not ship a `walkthroughs/` directory by default. If you
create one locally, use it to store walkthrough files that map game filenames
to sequences of actions.
60 changes: 60 additions & 0 deletions .github/workflows/copilot-setup-steps.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
name: "Copilot Setup Steps"

on:
workflow_dispatch:
push:
paths:
- .github/workflows/copilot-setup-steps.yml
pull_request:
paths:
- .github/workflows/copilot-setup-steps.yml

jobs:
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
copilot-setup-steps:
runs-on: ubuntu-latest

permissions:
contents: read

steps:
- name: Checkout code
uses: actions/checkout@v3

- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: "3.13"

- name: Install build tools
run: |
sudo apt-get update
sudo apt-get install -y build-essential gcc make

- name: Install jericho in development mode
run: |
python -m pip install --upgrade pip
pip install -e '.'
pip install pytest pytest-asyncio

- name: Download game ROMs from jericho-game-suite
run: |
GAME_SUITE_BASE_URL="https://raw.githubusercontent.com/BYU-PCCL/z-machine-games/master/jericho-game-suite"
mkdir -p roms
ROMS=(
905.z5 acorncourt.z5 advent.z5 adventureland.z5 afflicted.z8
anchor.z8 awaken.z5 balances.z5 ballyhoo.z3 curses.z5
cutthroat.z3 deephome.z5 detective.z5 dragon.z5 enter.z5
gold.z5 hhgg.z3 hollywood.z3 huntdark.z5 infidel.z3
inhumane.z5 jewel.z5 karn.z5 library.z5 loose.z5
lostpig.z8 ludicorp.z5 lurking.z3 moonlit.z5 murdac.z5
night.z5 omniquest.z5 partyfoul.z8 pentari.z5 planetfall.z3
plundered.z3 reverb.z5 seastalker.z3 sherbet.z5 sherlock.z5
snacktime.z8 sorcerer.z3 spellbrkr.z3 spirit.z5 temple.z5
theatre.z5 trinity.z4 tryst205.z5 weapon.z5 wishbringer.z3
yomomma.z8 zenon.z5 zork1.z5 zork2.z5 zork3.z5 ztuu.z5
)
for filename in "${ROMS[@]}"; do
echo "Downloading $filename..."
curl -fsSL "$GAME_SUITE_BASE_URL/$filename" -o "roms/$filename" || echo "Warning: could not download $filename"
done
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -336,3 +336,6 @@ ASALocalRun/

# Pip install files.
*.egg-info/

# Game ROMs
roms/
2 changes: 1 addition & 1 deletion frotz/src/games/afflicted.c
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ short afflicted_get_score() {
}

int afflicted_max_score() {
return 75;
return 117;
}

int afflicted_get_num_world_objs() {
Expand Down
2 changes: 1 addition & 1 deletion jericho/game_info.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
"name": "afflicted",
"rom": "afflicted.z8",
"seed": 0,
"walkthrough": 'read paper/e/search grate/search window/knock on window/w/n/x tables/note tables/ask angela about affliction/e/search ice/take hand/n/note vomit/note sink/note dryer/s/note counter/note stools/w/n/n/w/open cauldron/take foot/e/n/open dish washer/take right foot/s/s/s/take lamp/turn on lamp/n/n/n/d/open crate/u/s/s/x prep table/x shelf/take tongs/s/s/e/take eyes with tongs/w/n/n/n/x chopper/note it/x blade/open cover/turn screw/reach in chopper/open kit/wear tourniquet/take all/s/s/u/take key/read book/read killing/read culture/d/n/n/n/d/put eyes in body/put entrails in body/u/n/open dumpster/take all/s/d/put all in crate/no/u/s/s/s/s/w/search window/break window/x opener/take opener/e/n/kill sofia with opener',
"walkthrough": 'read paper/e/search grate/search window/knock on window/w/n/x tables/note tables/note roach/note rat/note produce/note window/ask angela about affliction/e/search ice/take hand/note floor/note faucet/note counter/note stools/n/note dispenser/note mouse/note vomit/note sink/note dryer/note toilet/s/w/n/note shelf/note grease/note pot/note pan/open lid/note kettle/close lid/open fridge/note lettuce/close fridge/s/take lamp/turn on lamp/n/n/note wall/w/note remnants/note pans/open cauldron/take foot/e/n/note table/note bleach/note servingware/open dish washer/take right foot/d/open crate/u/s/s/x prep table/x shelf/take tongs/s/s/e/take eyes with tongs/w/n/n/n/x chopper/x blade/open cover/turn screw/reach in chopper/open kit/wear tourniquet/take all/s/s/u/take key/read book/read killing/read culture/d/n/n/n/d/put eyes in body/put entrails in body/u/n/open dumpster/take all/s/d/put all in crate/no/u/s/s/s/s/w/search window/break window/x opener/take opener/e/n/kill sofia with opener',
"grammar" : "awake/awaken/wake;awake/awaken/wake up;bother/curses/darn/drat;carry/hold/take inventory;curse/damn/fuck/shit;disco/dance;exit/out/stand;get out/off/up;go/leave/run/walk;go/leave/run/walk through;go/leave/run/walk to bathroom;hints/hint;hints/hint off;hop/jump/skip;i/inv/inventory;info/about/help;l/look;listen;long/verbose;nap/sleep;no;normal/brief;notify;notify off;notify on;plugh/xyzzy;pronouns/nouns;q/quit;restart;restore;save;score;short/superbrie;sing;smell/sniff;solution/walkthru/walkthrou;sorry;stand up;think;transcrip/script;transcrip/script off;transcrip/script on;urinate/pee;use toilet;verify;version;wait/z;wave;y/yes;accuse OBJ;apply OBJ;awake/awaken/wake OBJ;awake/awaken/wake OBJ up;awake/awaken/wake up OBJ;burn/light OBJ;buy/purchase OBJ;carry/hold/take off OBJ;chop/cut/prune/slice OBJ;clean/dust/polish/rub/scrub/shine/sweep/wipe OBJ;clear/move/press/push/shift OBJ;climb/scale OBJ;climb/scale up/over OBJ;close/cover/shut OBJ;close/cover/shut up OBJ;cross/enter/go/leave/run/walk OBJ;damn/fuck/shit OBJ;discard/drop/throw OBJ;disrobe/doff/shed/remove OBJ;document/note OBJ;don/wear OBJ;drag/pull OBJ;drink/sip/swallow OBJ;eat OBJ;embrace/hug/kiss OBJ;flush OBJ;get in/into/on/onto OBJ;get off OBJ;get/carry/hold/take OBJ;go/leave/run/walk into/in/inside/through OBJ;hear OBJ;inspect/check/describe/examine/watch/x OBJ;l/look at OBJ;l/look inside/in/into/through OBJ;l/look under OBJ;lick/taste OBJ;listen to OBJ;lock OBJ;pick OBJ up;pick up OBJ;play OBJ;put OBJ down;put OBJ on;put down OBJ;put on OBJ;put on OBJ;reach in OBJ;reach inside OBJ;reach into OBJ;read OBJ;rotate/screw/turn/twist/unscrew OBJ;search OBJ;sit on top of OBJ;sit on/in/inside OBJ;slap/kick/attack/break/crack/destroy/fight/hit/kill/murder/punch/smash/thump/torture/wreck OBJ;smell/sniff OBJ;squash/squeeze OBJ;stand on OBJ;stroke/feel/touch OBJ;swing OBJ;swing on OBJ;switch OBJ;switch/rotate/screw/turn/twist/unscrew OBJ off;switch/rotate/screw/turn/twist/unscrew OBJ on;switch/rotate/screw/turn/twist/unscrew on OBJ;switch/rotate/screw/turn/twist/unscrew/close/cover/shut off OBJ;talk to OBJ;tap/knock OBJ;tap/knock on OBJ;uncover/open/unwrap OBJ;unlock OBJ;wave OBJ;adjust/set OBJ to OBJ;answer/say/shout/speak OBJ to OBJ;ask OBJ about OBJ;ask OBJ for OBJ;attach OBJ to OBJ;carry/hold/take OBJ off OBJ;consult OBJ on/about OBJ;discard/drop/throw OBJ at/against/on/onto OBJ;discard/drop/throw OBJ in/into/down OBJ;discard/drop/throw/put OBJ on/onto OBJ;display/present/show OBJ OBJ;display/present/show OBJ to OBJ;fasten/fix/tie OBJ to OBJ;feed/give/offer/pay OBJ OBJ;feed/give/offer/pay OBJ to OBJ;get/carry/hold/take OBJ with OBJ;insert OBJ in/into OBJ;l/look up OBJ in OBJ;lock OBJ with OBJ;open/unlock OBJ with OBJ;put OBJ in/inside/into OBJ;remove/get/carry/hold/take OBJ from OBJ;stab/attack/break/crack/destroy/fight/hit/kill/murder/punch/smash/thump/torture/wreck OBJ with OBJ;tell OBJ about OBJ;",
"max_word_length" : 9
}
Expand Down
Loading