pocket-creatures 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
File without changes
@@ -0,0 +1,49 @@
1
+ # ascii_art.py
2
+
3
+ ART = {
4
+ "happy": r"""
5
+ (\_/)
6
+ ( ^_^)
7
+ / >๐Ÿช Damn I feel good!
8
+ """,
9
+
10
+ "hungry": r"""
11
+ (\_/)
12
+ ( โ€ข_โ€ข)
13
+ / >๐Ÿฅบ Spare me a slice of the cheese?
14
+ """,
15
+
16
+ "tired": r"""
17
+ (\_/)
18
+ (-_- zZ)
19
+ / >๐Ÿ’ค So EEPY...
20
+ """,
21
+
22
+ "dirty": r"""
23
+ (\_/)
24
+ ( x_x)
25
+ / >๐Ÿงผ Covered in grime!
26
+ """,
27
+
28
+ "sad": r"""
29
+ (\_/)
30
+ ( ;_;)
31
+ / >๐Ÿ’” Sometimes I feel like no one cares about me...
32
+ """,
33
+
34
+ "ecstatic": r"""
35
+ (\_/)
36
+ ( โ˜†โ€ฟโ˜†)
37
+ / >๐ŸŽ‰ Over the moon!
38
+ """,
39
+
40
+ "neutral": r"""
41
+ (\_/)
42
+ ( โ€ขโ€ฟโ€ข)
43
+ / > I have no strong feelings either way.
44
+ """
45
+ }
46
+
47
+ def get_art(mood: str) -> str:
48
+ """Return ASCII art for the given mood."""
49
+ return ART.get(mood, ART["neutral"])
@@ -0,0 +1,108 @@
1
+ # game.py
2
+
3
+ import random
4
+ import time
5
+ from ascii_art import get_art
6
+ from save_manager import save_pet
7
+ from pet import Pet
8
+
9
+ COMMANDS = ["feed", "play", "sleep", "clean", "stats", "help", "quit"]
10
+
11
+
12
+ def stat_bar(value, length=12):
13
+ """Return a visual bar for a stat (0โ€“100)."""
14
+ filled = int((value / 100) * length)
15
+ empty = length - filled
16
+ return "โ–ˆ" * filled + "โ–‘" * empty
17
+
18
+
19
+ class Game:
20
+ def __init__(self, pet: Pet):
21
+ self.pet = pet
22
+ self.running = True
23
+
24
+ # -----------------------------
25
+ # Rendering
26
+ # -----------------------------
27
+ def render(self):
28
+ self.pet.update_stats()
29
+ mood = self.pet.get_mood()
30
+ art = get_art(mood)
31
+
32
+ print("\n" + "=" * 40)
33
+ print(f"{self.pet.name}'s Current Mood: {mood.upper()}")
34
+ print(art)
35
+ print("=" * 40)
36
+
37
+ def show_stats(self):
38
+ print(f"""
39
+ Stats for {self.pet.name}:
40
+ --------------------------
41
+ Hunger: {stat_bar(self.pet.hunger)} {self.pet.hunger:.1f}
42
+ Energy: {stat_bar(self.pet.energy)} {self.pet.energy:.1f}
43
+ Happiness: {stat_bar(self.pet.happiness)} {self.pet.happiness:.1f}
44
+ Cleanliness: {stat_bar(self.pet.cleanliness)} {self.pet.cleanliness:.1f}
45
+ """)
46
+
47
+ # -----------------------------
48
+ # Random Events
49
+ # -----------------------------
50
+ def random_event(self):
51
+ if random.random() < 0.15: # 15% chance per action
52
+ event = random.choice([
53
+ ("found a gold coin!", +5),
54
+ ("took a cute nap!", +10),
55
+ ("got scared by a drive-by!", -10),
56
+ ("ate a gyro!", +8),
57
+ ("stepped in poop!", -8)
58
+ ])
59
+ message, happiness_change = event
60
+ self.pet.happiness = max(0, min(100, self.pet.happiness + happiness_change))
61
+ print(f"\nโœจ Random Event: Your pet {message} (Happiness {happiness_change:+})")
62
+
63
+ # -----------------------------
64
+ # Command Handling
65
+ # -----------------------------
66
+ def handle_command(self, cmd):
67
+ cmd = cmd.lower().strip()
68
+
69
+ if cmd == "feed":
70
+ self.pet.feed()
71
+ print("๐ŸŽ Thanks for feeding me!")
72
+ elif cmd == "play":
73
+ self.pet.play()
74
+ print("๐ŸŽพ Thanks for playing with me!")
75
+ elif cmd == "sleep":
76
+ self.pet.sleep()
77
+ print("๐Ÿ’ค Your pet took a nap!")
78
+ elif cmd == "clean":
79
+ self.pet.clean()
80
+ print("๐Ÿงผ Thanks for cleaning me!")
81
+ elif cmd == "stats":
82
+ self.show_stats()
83
+ elif cmd == "help":
84
+ print("Available commands:", ", ".join(COMMANDS))
85
+ elif cmd == "quit":
86
+ print("Saving and exiting...")
87
+ save_pet(self.pet)
88
+ self.running = False
89
+ return
90
+ else:
91
+ print("Unknown command. Type 'help' for options.")
92
+
93
+ # After every action:
94
+ save_pet(self.pet)
95
+ self.random_event()
96
+
97
+ # -----------------------------
98
+ # Main Loop
99
+ # -----------------------------
100
+ def start(self):
101
+ print(f"\nWelcome back, {self.pet.name}!")
102
+ print("Type 'help' for a list of commands.\n")
103
+
104
+ while self.running:
105
+ self.render()
106
+ cmd = input("What would you like to do? > ")
107
+ self.handle_command(cmd)
108
+ time.sleep(0.3)
@@ -0,0 +1,25 @@
1
+ # main.py
2
+
3
+ from save_manager import load_pet, save_pet
4
+ from game import Game
5
+ from pet import Pet
6
+
7
+ def main():
8
+ print("๐Ÿพ Welcome to Pocket Creatures")
9
+
10
+ pet = load_pet()
11
+
12
+ if pet is None:
13
+ print("\nNo save file fouind - let's create a new pet!")
14
+ name = input("What would you like to name your Pocket Creature? ").strip()
15
+ if not name:
16
+ name = "Carl" # if no name is provided
17
+ pet = Pet(name)
18
+ save_pet(pet)
19
+ print(f"\n{name} has been created! Make sure to love him and good care of him!")
20
+
21
+ game = Game(pet)
22
+ game.start()
23
+
24
+ if __name__ == "__main__":
25
+ main()
@@ -0,0 +1,114 @@
1
+ # pet.py
2
+ import time
3
+
4
+ class Pet:
5
+ def __init__(self, name, hunger=50, energy=50, happiness=50, cleanliness=50, last_update=None):
6
+ self.name = name
7
+ self.hunger = hunger
8
+ self.energy = energy
9
+ self.happiness = happiness
10
+ self.cleanliness = cleanliness
11
+ self.last_update = last_update or time.time()
12
+
13
+ # ------------------------------------------------
14
+ # Internal Helpers
15
+ # ------------------------------------------------
16
+
17
+ def _clamp(self, value):
18
+ return max(0, min(100, value))
19
+
20
+ def _apply_decay(self):
21
+ """Decay stats based on time passed since last update."""
22
+ now = time.time()
23
+ elapsed = now - self.last_update #seconds
24
+
25
+ # Decay rates per second
26
+ hunger_decay = 0.01
27
+ energy_decay = 0.008
28
+ happiness_decay = 0.006
29
+ cleanliness_decay = 0.004
30
+
31
+ self.hunger = self._clamp(self.hunger - hunger_decay * elapsed)
32
+ self.energy = self._clamp(self.energy - energy_decay * elapsed)
33
+ self.happiness = self._clamp(self.happiness - happiness_decay * elapsed)
34
+ self.cleanliness = self._clamp(self.cleanliness - cleanliness_decay * elapsed)
35
+
36
+ self.last_update = now
37
+
38
+ # ------------------------------------------------
39
+ # Public methods
40
+ # ------------------------------------------------
41
+ def update_stats(self):
42
+ self._apply_decay()
43
+
44
+ def feed(self):
45
+ self.update_stats()
46
+ self.hunger = self._clamp(self.hunger + 25)
47
+ self.cleanliness = self._clamp(self.cleanliness - 5)
48
+
49
+ def play(self):
50
+ self.update_stats()
51
+ self.happiness = self._clamp(self.happiness + 20)
52
+ self.energy = self._clamp(self.energy - 10)
53
+ self.hunger = self._clamp(self.hunger - 5)
54
+
55
+ def sleep(self):
56
+ self.update_stats()
57
+ self.energy = self._clamp(self.energy + 30)
58
+ self.hunger = self._clamp(self.hunger - 10)
59
+
60
+ def clean(self):
61
+ self.update_stats()
62
+ self.cleanliness = self._clamp(self.cleanliness + 30)
63
+ self.happiness = self._clamp(self.happiness + 5)
64
+
65
+ # ------------------------------------------------
66
+ # Mood Logic
67
+ # ------------------------------------------------
68
+ def get_mood(self):
69
+ """Return a mood string based on the pets current stats"""
70
+ stats = {
71
+ "hunger": self.hunger,
72
+ "energy": self.energy,
73
+ "happiness": self.happiness
74
+ }
75
+
76
+ # Priority moods
77
+ if self.hunger < 20:
78
+ return "hungry"
79
+ if self.energy < 20:
80
+ return "tired"
81
+ if self.happiness < 20:
82
+ return "sad"
83
+
84
+ # Good moods
85
+ if all(v > 70 for v in stats.values()):
86
+ return "ecstatic"
87
+ if all(v > 50 for v in stats.values()):
88
+ return "happy"
89
+
90
+ return "neutral"
91
+
92
+ # -------------------------------------------------
93
+ # Serialization
94
+ # -------------------------------------------------
95
+ def to_dict(self):
96
+ return {
97
+ "name": self.name,
98
+ "hunger": self.hunger,
99
+ "energy": self.energy,
100
+ "happiness": self.happiness,
101
+ "cleanliness": self.cleanliness,
102
+ "last_update": self.last_update
103
+ }
104
+
105
+ @staticmethod
106
+ def from_dict(data):
107
+ return Pet(
108
+ name=data["name"],
109
+ hunger=data["hunger"],
110
+ energy=data["energy"],
111
+ happiness=data["happiness"],
112
+ cleanliness=data["cleanliness"],
113
+ last_update=data["last_update"]
114
+ )
@@ -0,0 +1,23 @@
1
+ # save_manager.py
2
+ import json
3
+ import os
4
+ from pet import Pet
5
+ import pet
6
+
7
+ SAVE_FILE = "save.json"
8
+
9
+ def save_pet(pet: Pet):
10
+ """Save the pets state to a JSON file."""
11
+ data = pet.to_dict()
12
+ with open(SAVE_FILE, "w") as f:
13
+ json.dump(data, f, indent=4)
14
+
15
+ def load_pet():
16
+ """Load the pet from disk. Returns a Pet or None if no save exists."""
17
+ if not os.path.exists(SAVE_FILE):
18
+ return None
19
+
20
+ with open(SAVE_FILE, "r") as f:
21
+ data = json.load(f)
22
+
23
+ return Pet.from_dict(data)
@@ -0,0 +1,426 @@
1
+ Metadata-Version: 2.1
2
+ Name: pocket-creatures
3
+ Version: 1.0.0
4
+ Summary: A terminal-based virtual pet game with ASCII art, stats, and random events.
5
+ Author: Robin
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/CaptainDreadbeard/pocket-creatures
8
+ Project-URL: Repository, https://github.com/CaptainDreadbeard/pocket-creatures
9
+ Project-URL: Issues, https://github.com/CaptainDreadbeard/pocket-creatures
10
+ Requires-Python: >=3.8
11
+ Description-Content-Type: text/markdown
12
+
13
+ # ๐Ÿพ pocket-creatures
14
+
15
+ > **A cozy little virtual pet game that lives in your terminal.**
16
+ > Adopt a creature, keep it happy, and watch it grow โ€” all from your command line!
17
+
18
+ ---
19
+
20
+ ```
21
+ /\_/\ (\(\
22
+ ( o.o ) ( -.-)
23
+ > ^ < o_(")(")
24
+
25
+ Your new best friend is waiting...
26
+ ```
27
+
28
+ ---
29
+
30
+ ## ๐Ÿ“– What Is pocket-creatures?
31
+
32
+ **pocket-creatures** is a terminal-based virtual pet game written in Python. You adopt a creature, give it a name, and take care of it by feeding it, playing with it, and putting it to sleep. Your pet has real stats โ€” hunger, happiness, health, and energy โ€” that change over time. Neglect your creature and it'll get grumpy; shower it with attention and it'll thrive!
33
+
34
+ Random events keep things interesting: your pet might find a treasure, catch a cold, or learn a new trick when you least expect it.
35
+
36
+ **Perfect for:**
37
+ - Python beginners who want a fun first project to install and run
38
+ - Anyone who misses the Tamagotchi era
39
+ - People who spend a lot of time in the terminal and want some company
40
+
41
+ ---
42
+
43
+ ## โœจ Features
44
+
45
+ - ๐Ÿฑ **Multiple creature types** โ€” each with unique ASCII art and personality
46
+ - ๐Ÿ“Š **Real-time stats** โ€” track Hunger, Happiness, Health, and Energy at a glance
47
+ - ๐ŸŽฒ **Random events** โ€” surprises that keep every session fresh
48
+ - ๐Ÿ’พ **Auto-save** โ€” your pet's progress is saved automatically when you quit
49
+ - ๐ŸŽจ **ASCII art animations** โ€” your creature reacts visually to its mood
50
+ - ๐Ÿ† **Milestones & aging** โ€” watch your creature grow through life stages
51
+ - ๐Ÿฉบ **Status effects** โ€” pets can get sick, tired, or extra-hyper
52
+ - ๐ŸŒˆ **Colourful terminal UI** โ€” works on Windows, macOS, and Linux
53
+
54
+ ---
55
+
56
+ ## ๐Ÿ–ฅ๏ธ Before You Begin: What You'll Need
57
+
58
+ Don't worry if you've never run a Python program before โ€” this section walks you through everything step by step.
59
+
60
+ ### 1. Check if Python is Installed
61
+
62
+ Open your terminal (instructions below) and type:
63
+
64
+ ```bash
65
+ python --version
66
+ ```
67
+
68
+ or, on some systems:
69
+
70
+ ```bash
71
+ python3 --version
72
+ ```
73
+
74
+ You should see something like `Python 3.8.0` or higher. **pocket-creatures requires Python 3.8 or newer.**
75
+
76
+ > **How to open a terminal:**
77
+ > - **Windows:** Press `Win + R`, type `cmd`, press Enter. Or search for "Command Prompt" or "Windows Terminal" in the Start Menu.
78
+ > - **macOS:** Press `Cmd + Space`, type "Terminal", press Enter.
79
+ > - **Linux:** Press `Ctrl + Alt + T`, or search for "Terminal" in your app launcher.
80
+
81
+ ### 2. Install Python (if needed)
82
+
83
+ If you got an error like `'python' is not recognized` or your version is below 3.8:
84
+
85
+ 1. Visit [https://www.python.org/downloads/](https://www.python.org/downloads/)
86
+ 2. Click the big yellow **"Download Python"** button
87
+ 3. Run the installer
88
+ 4. โš ๏ธ **Windows users:** On the first screen of the installer, make sure to tick the box that says **"Add Python to PATH"** before clicking Install!
89
+ 5. Close and reopen your terminal, then check `python --version` again
90
+
91
+ ---
92
+
93
+ ## ๐Ÿ“ฆ Installation
94
+
95
+ Once Python is ready, installing pocket-creatures is just one command!
96
+
97
+ ```bash
98
+ pip install pocket-creatures
99
+ ```
100
+
101
+ > **What is `pip`?** It's Python's package manager โ€” a tool that downloads and installs Python programs from the internet automatically. It comes bundled with Python.
102
+
103
+ If you see a "permission denied" error, try:
104
+
105
+ ```bash
106
+ pip install --user pocket-creatures
107
+ ```
108
+
109
+ ### Upgrading to the Latest Version
110
+
111
+ Already have it installed and want the newest version?
112
+
113
+ ```bash
114
+ pip install --upgrade pocket-creatures
115
+ ```
116
+
117
+ ### Verifying the Installation
118
+
119
+ After installing, confirm it worked by checking the version:
120
+
121
+ ```bash
122
+ pocket-creatures --version
123
+ ```
124
+
125
+ You should see a version number printed. If you do โ€” you're all set! ๐ŸŽ‰
126
+
127
+ ---
128
+
129
+ ## ๐Ÿš€ Running the Game
130
+
131
+ Starting pocket-creatures is simple. In your terminal, type:
132
+
133
+ ```bash
134
+ pocket-creatures
135
+ ```
136
+
137
+ The game will launch directly in your terminal window. On your **very first run**, you'll be greeted with a welcome screen and asked to:
138
+
139
+ 1. **Choose your creature type** โ€” pick the one that calls to you!
140
+ 2. **Give your creature a name** โ€” make it personal ๐Ÿพ
141
+ 3. **Watch your adventure begin**
142
+
143
+ > **Tip:** Make your terminal window a bit wider and taller for the best experience. Aim for at least 80 columns ร— 24 rows.
144
+
145
+ ### Alternative Launch Commands
146
+
147
+ ```bash
148
+ # You can also run it as a Python module if the command isn't found:
149
+ python -m pocket_creatures
150
+
151
+ # Or with python3 specifically:
152
+ python3 -m pocket_creatures
153
+ ```
154
+
155
+ ---
156
+
157
+ ## ๐ŸŽฎ How to Play
158
+
159
+ ### The Main Screen
160
+
161
+ When you launch the game, you'll see your creature displayed with ASCII art in the centre of the screen. Around it you'll find:
162
+
163
+ ```
164
+ โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
165
+ โ•‘ ๐Ÿพ Biscuit | Age: 3 days โ•‘
166
+ โ• โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ
167
+ โ•‘ โ•‘
168
+ โ•‘ /\_/\ โ•‘
169
+ โ•‘ ( ^.^ ) "I'm hungry!" โ•‘
170
+ โ•‘ > ~ < โ•‘
171
+ โ•‘ โ•‘
172
+ โ• โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ
173
+ โ•‘ โค Health โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘ 80% โ•‘
174
+ โ•‘ ๐Ÿ˜Š Happiness โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘ 60% โ•‘
175
+ โ•‘ ๐Ÿ– Hunger โ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 40% โ•‘
176
+ โ•‘ โšก Energy โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 100% โ•‘
177
+ โ• โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ
178
+ โ•‘ [F]eed [P]lay [S]leep [Q]uit โ•‘
179
+ โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
180
+ ```
181
+
182
+ ### Controls & Commands
183
+
184
+ Press a key at any time โ€” **no need to press Enter** after single-letter commands!
185
+
186
+ | Key | Action | Effect on your pet |
187
+ |-----|--------|--------------------|
188
+ | `F` | **Feed** | Reduces hunger, slightly increases happiness |
189
+ | `P` | **Play** | Boosts happiness and energy (costs some hunger) |
190
+ | `S` | **Sleep** | Restores energy and health (pet is unavailable while sleeping) |
191
+ | `M` | **Medicine** | Cures sickness (only appears when your pet is ill) |
192
+ | `C` | **Clean** | Cleans up your pet's space, boosts happiness |
193
+ | `I` | **Info** | Shows detailed stats and your creature's history |
194
+ | `H` | **Help** | Displays an in-game help screen |
195
+ | `Q` | **Quit** | Saves your game and exits |
196
+
197
+ > **Keyboard shortcut tip:** You can also use the **arrow keys** to navigate menus and press **Enter** to confirm selections.
198
+
199
+ ---
200
+
201
+ ## ๐Ÿ“Š Understanding Your Pet's Stats
202
+
203
+ Your creature has four core stats. They all change over time, so check in regularly!
204
+
205
+ ### โค๏ธ Health (0โ€“100)
206
+ Your pet's overall wellbeing. Health drops slowly when your pet is hungry or exhausted for too long. Give medicine when sick.
207
+ - **80โ€“100:** Thriving
208
+ - **50โ€“79:** Doing okay
209
+ - **20โ€“49:** Needs attention
210
+ - **0โ€“19:** Critical โ€” act fast!
211
+
212
+ ### ๐Ÿ˜Š Happiness (0โ€“100)
213
+ How cheerful your creature is. It drops when your pet is ignored, hungry, or sick.
214
+ - Play with your pet and keep it fed to maintain high happiness.
215
+ - A very unhappy pet may refuse to eat or play.
216
+
217
+ ### ๐Ÿ– Hunger (0โ€“100)
218
+ How hungry your pet is โ€” **higher is hungrier.** Feed your pet before this gets too high!
219
+ - Hunger rises steadily over time.
220
+ - At 80+, your pet starts losing health.
221
+ - At 100, your pet is starving โ€” health drops quickly.
222
+
223
+ ### โšก Energy (0โ€“100)
224
+ How energetic your creature is. Playing costs energy; sleeping restores it.
225
+ - At low energy, your pet becomes sluggish and won't want to play.
226
+ - At 0, your pet falls asleep automatically.
227
+
228
+ ---
229
+
230
+ ## ๐ŸŽฒ Random Events
231
+
232
+ Life with your creature is full of surprises! Random events can happen any time you interact with your pet. Some are good, some are bad โ€” all are part of the adventure.
233
+
234
+ **Examples of events you might encounter:**
235
+
236
+ | Event | Description |
237
+ |-------|-------------|
238
+ | ๐ŸŽ **Found a treasure!** | Your pet discovered a shiny object โ€” happiness boost! |
239
+ | ๐Ÿคง **Caught a cold** | Your pet is sick and needs medicine |
240
+ | โœจ **Learned a trick!** | Your creature discovered a new skill |
241
+ | โ›ˆ๏ธ **Stormy night** | Bad weather made your pet anxious โ€” happiness drops |
242
+ | ๐ŸŒŸ **Extra energetic** | Your pet is buzzing with energy today |
243
+ | ๐Ÿ’ค **Feeling extra sleepy** | Your pet needs more rest than usual |
244
+
245
+ > Events are displayed as a pop-up message on screen. Read them carefully โ€” some require action from you!
246
+
247
+ ---
248
+
249
+ ## ๐ŸŒฑ Creature Life Stages
250
+
251
+ Your creature grows and changes over time. Each life stage brings new ASCII art and behaviors:
252
+
253
+ | Stage | Age | Description |
254
+ |-------|-----|-------------|
255
+ | ๐Ÿฅš **Egg** | Day 0 | Your adventure begins! |
256
+ | ๐Ÿฃ **Baby** | Days 1โ€“2 | Tiny and needy โ€” check in often |
257
+ | ๐Ÿพ **Young** | Days 3โ€“6 | Playful and curious |
258
+ | ๐ŸŒŸ **Adult** | Days 7โ€“13 | Well-rounded and independent |
259
+ | ๐Ÿ‘‘ **Elder** | Day 14+ | Wise and a little slower-paced |
260
+
261
+ ---
262
+
263
+ ## ๐Ÿ’พ Saving & Loading
264
+
265
+ pocket-creatures **automatically saves your progress** whenever you quit with `Q`. The next time you launch the game, your pet will be right where you left it.
266
+
267
+ ### Where is my save file?
268
+
269
+ | Operating System | Save file location |
270
+ |---|---|
271
+ | Windows | `C:\Users\YourName\AppData\Local\pocket_creatures\` |
272
+ | macOS | `~/Library/Application Support/pocket_creatures/` |
273
+ | Linux | `~/.local/share/pocket_creatures/` |
274
+
275
+ > **Note:** `~` means your home folder. `YourName` is your Windows username.
276
+
277
+ ### Backing Up Your Pet
278
+
279
+ Want to keep your save safe? Copy the `save.json` file from the folder above to a safe place. To restore it, just copy it back.
280
+
281
+ ---
282
+
283
+ ## ๐Ÿ› ๏ธ Troubleshooting
284
+
285
+ ### "pocket-creatures: command not found"
286
+
287
+ This usually means Python's script folder isn't in your system's PATH. Try these alternatives:
288
+
289
+ ```bash
290
+ python -m pocket_creatures
291
+ # or
292
+ python3 -m pocket_creatures
293
+ ```
294
+
295
+ **Permanent fix on Windows:**
296
+ 1. Search for "Environment Variables" in the Start Menu
297
+ 2. Click "Edit the system environment variables"
298
+ 3. Click "Environment Variablesโ€ฆ"
299
+ 4. Under "User variables", find `Path` and click Edit
300
+ 5. Add `%APPDATA%\Python\Python3x\Scripts` (replace `3x` with your Python version number, e.g. `312`)
301
+ 6. Restart your terminal
302
+
303
+ ---
304
+
305
+ ### "pip: command not found"
306
+
307
+ Try using `pip3` instead:
308
+
309
+ ```bash
310
+ pip3 install pocket-creatures
311
+ ```
312
+
313
+ Or invoke pip through Python directly:
314
+
315
+ ```bash
316
+ python -m pip install pocket-creatures
317
+ # or
318
+ python3 -m pip install pocket-creatures
319
+ ```
320
+
321
+ ---
322
+
323
+ ### The ASCII art looks broken or garbled
324
+
325
+ Your terminal may not support Unicode characters fully. Try:
326
+
327
+ 1. **Windows:** Use **Windows Terminal** (download free from the Microsoft Store) instead of the classic Command Prompt
328
+ 2. **All platforms:** Make sure your terminal's font is set to a monospace font like `Consolas`, `Courier New`, or `Fira Code`
329
+ 3. Set your terminal's encoding to UTF-8:
330
+ ```bash
331
+ # Windows Command Prompt only:
332
+ chcp 65001
333
+ ```
334
+
335
+ ---
336
+
337
+ ### Colors aren't showing / terminal looks plain
338
+
339
+ Some older terminals don't support colors. pocket-creatures detects this automatically and falls back to plain text. For the best experience, use:
340
+ - **Windows:** Windows Terminal or VS Code's integrated terminal
341
+ - **macOS:** The default Terminal app or iTerm2
342
+ - **Linux:** Any modern terminal emulator (gnome-terminal, konsole, alacritty, etc.)
343
+
344
+ ---
345
+
346
+ ### My pet's stats seem wrong after reloading
347
+
348
+ If your save file gets corrupted (this is rare!), you can reset your game:
349
+
350
+ ```bash
351
+ pocket-creatures --reset
352
+ ```
353
+
354
+ > โš ๏ธ **Warning:** This will permanently delete your current pet. Make a backup first if you want to keep your save!
355
+
356
+ ---
357
+
358
+ ### The game crashes on startup
359
+
360
+ 1. Make sure you have Python 3.8 or newer: `python --version`
361
+ 2. Try reinstalling: `pip install --upgrade --force-reinstall pocket-creatures`
362
+ 3. Check if there's an error message โ€” if so, copy the full message and open an issue on GitHub (link below)
363
+
364
+ ---
365
+
366
+ ## ๐Ÿ“ Project Structure (for the curious)
367
+
368
+ If you're a developer or just want to peek under the hood:
369
+
370
+ ```
371
+ pocket_creatures/
372
+ โ”œโ”€โ”€ __init__.py # Package entry point
373
+ โ”œโ”€โ”€ __main__.py # Launch point (python -m pocket_creatures)
374
+ โ”œโ”€โ”€ game.py # Core game loop and logic
375
+ โ”œโ”€โ”€ creature.py # Creature class, stats, and life stages
376
+ โ”œโ”€โ”€ events.py # Random event system
377
+ โ”œโ”€โ”€ renderer.py # ASCII art and terminal UI rendering
378
+ โ”œโ”€โ”€ save.py # Save/load game state to disk
379
+ โ””โ”€โ”€ assets/
380
+ โ””โ”€โ”€ ascii_art/ # ASCII art files for each creature and mood
381
+ ```
382
+
383
+ ---
384
+
385
+ ## ๐Ÿค Contributing
386
+
387
+ Found a bug? Have an idea for a new creature type or random event? Contributions are warmly welcomed!
388
+
389
+ 1. Fork the repository on GitHub
390
+ 2. Create a feature branch: `git checkout -b my-new-feature`
391
+ 3. Make your changes and add tests if applicable
392
+ 4. Open a Pull Request with a clear description of what you changed
393
+
394
+ Please be kind and constructive in all interactions โ€” this is a friendly project!
395
+
396
+ ---
397
+
398
+ ## ๐Ÿ› Reporting Bugs
399
+
400
+ If something goes wrong, please open a GitHub issue and include:
401
+
402
+ - Your operating system and version (e.g. Windows 11, macOS 14, Ubuntu 24.04)
403
+ - Your Python version (`python --version`)
404
+ - Your pocket-creatures version (`pocket-creatures --version`)
405
+ - The full error message or a description of what happened
406
+ - Steps to reproduce the problem
407
+
408
+ ---
409
+
410
+ ## ๐Ÿ“œ License
411
+
412
+ pocket-creatures is released under the **MIT License** โ€” free to use, modify, and share. See `LICENSE` for full details.
413
+
414
+ ---
415
+
416
+ ## ๐Ÿ™ Acknowledgements
417
+
418
+ - Inspired by the classic Tamagotchi virtual pets of the 1990s
419
+ - ASCII art crafted with love
420
+ - Built with โค๏ธ for anyone who ever wished their terminal had a little more life in it
421
+
422
+ ---
423
+
424
+ <p align="center">
425
+ Made with ๐Ÿพ &nbsp;|&nbsp; Happy creature-keeping!
426
+ </p>
@@ -0,0 +1,11 @@
1
+ pocket_creatures/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
2
+ pocket_creatures/ascii_art.py,sha256=iiYw4gYxdc5P2MW29qJqtc4OnXbiAcfwnsv_cbKflao,915
3
+ pocket_creatures/game.py,sha256=9LDYxNbH7wq4RkkA2dC86L8zu-RIodndxMKGfyqOZxs,3453
4
+ pocket_creatures/main.py,sha256=jzyJUPd6wWm7IkaOV5fxY0H9zo6bkwMMx5MSTf2aDrQ,655
5
+ pocket_creatures/pet.py,sha256=GqwCn97X9yy_STgp8b7AG7BL9roMGcEpoffMZx_AKUA,3713
6
+ pocket_creatures/save_manager.py,sha256=0QltfvaAPlfp58YtehCbUM2ipD3Un8RX_bGivTrVsgY,519
7
+ pocket_creatures-1.0.0.dist-info/METADATA,sha256=oIiofMgP3kb1odwmqaOOT96Uq7XUWM-CfwoZPqChf1Y,14770
8
+ pocket_creatures-1.0.0.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
9
+ pocket_creatures-1.0.0.dist-info/entry_points.txt,sha256=IPiu2IKRKAMv-IRXT_RBSot61eo6KfWRDxrudWml9TE,64
10
+ pocket_creatures-1.0.0.dist-info/top_level.txt,sha256=6ZJF886FBGM4DZQPTGy6UXQaPGxmm56b8pja_dkJ4lI,17
11
+ pocket_creatures-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.3.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ pocket-creatures = pocket_creatures.main:main
@@ -0,0 +1 @@
1
+ pocket_creatures