Skip to content

Commit 1e8e30c

Browse files
EngineerDogItaEngineerDogIta
authored
Merge pull request #1 from EngineerDogIta/claude/document-project-objective-QNgJA
2 parents 8079367 + 407dc77 commit 1e8e30c

4 files changed

Lines changed: 401 additions & 135 deletions

File tree

‎GAMEPLAY.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Gameplay Documentation
2+
3+
## How to Run
4+
5+
```bash
6+
python3 main.py
7+
```
8+
9+
No external dependencies required. Python 3.x is sufficient.
10+
11+
---
12+
13+
## Game Flow
14+
15+
### 1. Startup Sequence
16+
17+
When launched, the game prints a themed loading sequence that mimics a Fallout
18+
terminal, with a short delay between each line (controlled by `EFFECT_WAIT_SEC`
19+
in `config.json`):
20+
21+
```
22+
Excecuting Debug of the secretCodes.db
23+
24+
initiating preliminary processes
25+
secretCodes.db -> loaded
26+
debug process phase 1/2 -> 'OK'
27+
debug process phase 2/2 -> taking just from 0,122 line
28+
...PROCESSING TEXT..
29+
decrypting MASTER_PASSWORD
30+
31+
Extract from the secretCodes.db
32+
```
33+
34+
### 2. The Word List
35+
36+
After the startup sequence, the game displays all candidate words on one line:
37+
38+
```
39+
jeans ciana lizza vello cesio greve della prude arare
40+
```
41+
42+
- Between **4 and 10** words are shown (configurable via `MIN_NUM_WORD` / `MAX_NUM_WORD`).
43+
- All words have the **same length** (default: 5 characters, set by `LENGHT_PER_WORD`).
44+
- Words are drawn randomly from the word list file (default: Italian).
45+
- One of these words is the hidden **master password**.
46+
47+
### 3. Attempts
48+
49+
The number of attempts is calculated as:
50+
51+
```
52+
attempts = floor(number_of_candidate_words / DIFFICULTY)
53+
```
54+
55+
With the default `DIFFICULTY = 2` and 9 candidate words, the player gets **4 attempts**.
56+
57+
> **Note:** Higher `DIFFICULTY` = fewer attempts = harder game.
58+
59+
---
60+
61+
## Player Interaction
62+
63+
Each round the game prompts:
64+
65+
```
66+
attempt num > 4
67+
verifyFun() insert string ->
68+
```
69+
70+
The player types one of the displayed words and presses Enter.
71+
72+
### Valid Input
73+
74+
The guess **must** be one of the words shown on screen. Any other input is rejected:
75+
76+
```
77+
INPUT NOT VALID
78+
```
79+
80+
---
81+
82+
## Feedback System
83+
84+
After each **wrong** guess, the game shows how many letters from the guess
85+
appear **anywhere** in the master password:
86+
87+
```
88+
ERROR arare -> 3/5
89+
WRONG WORD attempt num > 3
90+
```
91+
92+
This means: 3 out of 5 letters in `arare` are found somewhere in the master
93+
password. Use this to eliminate or prioritise words.
94+
95+
> **Important:** The hint counts letter *presence*, not *position*.
96+
> A letter is counted once per occurrence in the guess, regardless of where it
97+
> sits in the master password.
98+
99+
### Hint Examples (master password: `jeans`)
100+
101+
| Guess | Hint | Reasoning |
102+
|---------|------|-----------|
103+
| `arare` | 3/5 | `a`, `r`, `e` appear in `jeans` (a=yes, r=no, a=yes, r=no, e=yes → 3) |
104+
| `della` | 2/5 | `e`, `a` appear in `jeans` |
105+
| `lizza` | 1/5 | only `a` appears in `jeans` |
106+
107+
---
108+
109+
## End States
110+
111+
### Win — Correct Guess
112+
113+
```
114+
ACCESS GRANTED
115+
A WINNAR IS YUO
116+
```
117+
118+
### Lose — Attempts Exhausted
119+
120+
```
121+
COMPUTER LOCKED
122+
123+
NO MORE ATTEMPTS AVAILABLE
124+
```
125+
126+
---
127+
128+
## Full Session Example
129+
130+
Below is a real session trace (9 candidate words, 4 attempts, master = `jeans`):
131+
132+
```
133+
Excecuting Debug of the secretCodes.db
134+
135+
initiating preliminary processes
136+
secretCodes.db -> loaded
137+
debug process phase 1/2 -> 'OK'
138+
debug process phase 2/2 -> taking just from 0,122 line
139+
...PROCESSING TEXT..
140+
decrypting MASTER_PASSWORD
141+
142+
Extract from the secretCodes.db
143+
144+
jeans ciana lizza vello cesio greve della prude arare
145+
146+
attempt num > 4
147+
verifyFun() insert string -> arare
148+
ERROR arare -> 3/5
149+
WRONG WORD attempt num > 3
150+
151+
attempt num > 3
152+
verifyFun() insert string -> della
153+
ERROR della -> 2/5
154+
WRONG WORD attempt num > 2
155+
156+
attempt num > 2
157+
verifyFun() insert string -> lizza
158+
ERROR lizza -> 1/5
159+
WRONG WORD attempt num > 1
160+
161+
attempt num > 1
162+
verifyFun() insert string -> jeans
163+
ACCESS GRANTED
164+
A WINNAR IS YUO
165+
```
166+
167+
---
168+
169+
## Configuration Quick Reference
170+
171+
All parameters live in `config.json`:
172+
173+
| Key | Default | Effect |
174+
|------------------|--------------------------|--------|
175+
| `NAME_FILE` | `wordListItaliano.txt` | Word list source file |
176+
| `EFFECT_WAIT_SEC`| `0.1` | Delay (seconds) between startup lines |
177+
| `MAX_NUM_WORD` | `10` | Maximum candidate words shown |
178+
| `MIN_NUM_WORD` | `4` | Minimum candidate words shown |
179+
| `LENGHT_PER_WORD`| `5` | Exact length of all words |
180+
| `DIFFICULTY` | `2` | Divides candidate count to set attempts |
181+
182+
---
183+
184+
## Strategy Tips
185+
186+
- Start with words that share **few** letters with each other — this maximises
187+
the information you gain from the hint.
188+
- A hint of `0/5` is extremely useful: it eliminates every letter in that word
189+
from consideration.
190+
- A hint equal to the word length (e.g. `5/5`) means all letters of your guess
191+
are present in the master password, though not necessarily in the same order.

‎OBJECTIVE.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Project Objective
2+
3+
## Overview
4+
5+
**Fallout Hacking Game** is a command-line word-guessing game that recreates the terminal hacking minigame from the Fallout video game series. The project is a fan-made, pure-Python implementation with no external dependencies.
6+
7+
## Core Goal
8+
9+
Provide a faithful, playable recreation of the Fallout hacking minigame in a terminal environment, where the player must deduce a master password from a set of candidate words within a limited number of attempts.
10+
11+
## Gameplay Objective
12+
13+
1. The game presents the player with a list of 4–10 randomly selected words, all of equal length.
14+
2. One of those words is the hidden master password.
15+
3. The player must guess the correct word within a limited number of attempts (`candidates / DIFFICULTY`).
16+
4. After each wrong guess, the game provides a hint: how many letters from the guess appear anywhere in the master password (e.g., `2/5`).
17+
5. The player wins by guessing the correct word before running out of attempts.
18+
19+
## Design Goals
20+
21+
- **Authenticity**: Mimics the retro terminal aesthetic of Fallout's hacking sequences, including themed output messages and a simulated loading effect.
22+
- **Simplicity**: Pure Python 3, no external dependencies — runs anywhere Python is installed.
23+
- **Configurability**: All game parameters (word list, word length, attempt count, difficulty, visual delay) are controlled via `config.json`.
24+
- **Extensibility**: Supports any language by swapping the word list file (one word per line).
25+
- **Code quality**: PEP 8 compliant, enforced via `flake8` and automated CI/CD checks.
26+
27+
## Technical Scope
28+
29+
| Concern | Approach |
30+
|---|---|
31+
| Language | Python 3.x |
32+
| Word source | Plaintext file (default: Italian, 40k+ words) |
33+
| Word filtering | Words are filtered to an exact configured length |
34+
| Hint system | Letter-overlap count between guess and master password |
35+
| Difficulty | Attempts = `floor(num_candidates / DIFFICULTY)` |
36+
| Configuration | `config.json` — no code changes needed to tune the game |
37+
38+
## Out of Scope
39+
40+
- Graphical or web-based interface
41+
- Networked or multiplayer modes
42+
- Ownership of the Fallout trademark (this is purely a fan project)

‎config.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@
33
"EFFECT_WAIT_SEC": 0.1,
44
"MAX_NUM_WORD": 10,
55
"MIN_NUM_WORD": 4,
6-
"LENGHT_PER_WORD": 5,
6+
"LENGTH_PER_WORD": 5,
77
"DIFFICULTY": 2
88
}

0 commit comments

Comments
 (0)