stage 8 reworked

Author: DamoM73

_static/custom.css

@@ -54,6 +54,24 @@ h4 {
 }
 
 /* Sidebar background (covers gutter left of nav) */
+body:not([data-theme="dark"]) {
+  background: #ffdfb4 !important;
+}
+body:not([data-theme="dark"]) .page {
+  background: #ffdfb4 !important;
+}
+.main,
+.main-content,
+.content,
+.article {
+  background: #ffffff !important;
+}
+body[data-theme="dark"] .main,
+body[data-theme="dark"] .main-content,
+body[data-theme="dark"] .content,
+body[data-theme="dark"] .article {
+  background: transparent !important;
+}
 .sidebar-drawer,
 .sidebar,
 .sidebar-container,
@@ -117,17 +135,14 @@ h4 {
   ) !important;
 }
 
-/* Override base background (left gutter) while keeping content white */
-html,
-body {
-  background: #ffdfb4 !important;
-}
-.page {
-  background: #ffdfb4 !important; /* ensure outer layout uses the gutter color */
+/* Sidebar subtitle via pseudo-element */
+.sidebar-brand-text::after {
+  content: "Object Orentated Python";
+  display: block;
+  font-size: 0.9rem;
+  color: var(--color-foreground-muted);
+  margin-top: 0.1rem;
 }
-.main,
-.main-content,
-.content,
-.article {
-  background: #ffffff !important; /* keep center content area white */
+.sidebar-brand-text {
+  color: #000000 !important;
 }

build/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 18f0f6d15f8fe781a14a84e8cb0397cc
+config: 17e558abee438519930b4a4f55f41399
 tags: 645f666f9bcd5a90fca523b33c5a78b7

build/.buildinfo.bak

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b66cfdc9d94f3475b7b891ac0a6eab11
+config: f7ef413303263d410bc28d1a0d115a6d
 tags: 645f666f9bcd5a90fca523b33c5a78b7

build/.doctrees/environment.pickle

@@ -1,45 +1,48 @@
 # Stage 7 - Victory Conditions
 
-```{topic} In this lesson you will:
-
-- Count the number of enemies
-- Create victory conditions
+```{topic} Learning Intentions
+In this lesson you will:
+* Know the difference between class variables and normal (instance) variables in an OOP programme.
+* Understand how objects can share information by using a class variable.
+* Know when and where to put if-statements inside methods so an object can make decisions.
+* Create and change class variables so objects can share the same data.
+* Write methods that use if-statements to change what an object does based on what is happening in the programme.
 ```
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/hTGv542obJo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
 ## Introduction
 
-We are close to finishing our text-based adventure game. We now have a dungeon in which the user can move around, collect different items, interact with different characters and have the result of those interactions determined by the character type.
+We’re almost done with our text-based adventure game. You now have a dungeon where the player can move around, pick up items, and talk or fight with different characters. What happens in these interactions depends on the type of character they meet.
 
-In this stage we will look at establishing victory conditions for the game.
+In this stage, you’re going to set up how the player wins the game.
 
-We will do this by:
+You will do this by:
 
-- keeping a count of the number of enemies
-- reducing the enemy count when each enemy is defeated
-- declare the player victorious when there are no enemies left
+* counting how many enemies exist
+* lowering that count each time an enemy is defeated
+* checking when the count reaches zero so the player wins the game
 
 ### Class Diagram
 
-Look to our class diagram for this stage and you will notice something new. 
+Have a look at the class diagram for this stage and you’ll see something new.
 
-The `Enemy` class has a new: 
+The `Enemy` class now has:
 
-- `num_of_enemy` attribute
-- `get_num_of_enemy` method
+* a `num_of_enemy` attribute
+* a `get_num_of_enemy` method
 
 ![lesson 7 class diagram](./assets/lesson_7_class_diagram.png)
 
-Notice the `num_of_enemy` attribute is underlined. This indicates that this is a **class variable**. This means that the variable is shared across to all instances of that class. Each instance of that class can access and modify the variable, and any changes will be shared with other classes.
+The `num_of_enemy` attribute is underlined in the diagram. That underline shows it’s a **class variable**. A class variable is shared by every object made from that class. All `Enemy` objects can read it and change it, and whenever one object changes it, the others see the new value too.
 
-In our example, the `num_of_enemy` will be shared with all the `Enemy` objects we create in our game.
+In this game, `num_of_enemy` keeps track of how many `Enemy` objects exist, and every enemy you create will share that same number.
 
 ## Count Number of Enemies
 
-To keep track of the number of `Enemy` objects in the game, we need to add a **class variable** to the `Enemy` class.
+To keep track of how many `Enemy` objects are in the game, we need to add a **class variable** to the `Enemy` class.
 
-So we need to open the **character.py** file, and add the highlighted code below.
+Open **character.py** and add the highlighted code shown below.
 
 ```{code-block} python
 :linenos:
@@ -108,13 +111,14 @@ Save the code, and **run** it to ensure there are no errors.
 
 **Investigating** the code:
 
-- `num_of_enemy = 0` &rarr; creates our **class variable**
-  - important to note the location and the indent level of **class variables**:
-    - need to be placed before the `__init__` method
-    - indented once &rarr; same level as method definitions
-  - also note that, unlike the other attributes, `num_of_enemy` does start with `self` because it is a **class variable**
-- `Enemy.num_of_enemy += 1` &rarr; increases `num_of_enemy` by one each time a new `Enemy` object is created.
-  - since `__init__` runs each time a new enemy is made, the value of `num_of_enemy` will increase
+```{admonition} Code Explaination
+* `num_of_enemy = 0` &rarr; this creates the **class variable**.
+  * Class variables must be written **before** the `__init__` method.
+  * They are indented once, at the same level as the methods.
+  * It does **not** use `self` because it belongs to the whole class, not to one object.
+* `Enemy.num_of_enemy += 1` &rarr; this adds 1 to `num_of_enemy` every time a new `Enemy` is created.
+  * Because `__init__` runs whenever you make a new enemy, the total number of enemies goes up each time.
+```
 
 Now that we are keeping track of the number of enemies, but we can't see what that number is. So let's create a method to find out how many enemies are in the dungeon
 
@@ -188,18 +192,20 @@ class Enemy(Character):
 
 Let's investigate that method:
 
-- `def get_num_of_enemy():` &rarr; defines the method
-  - there is no `self` argument &rarr; this method is not tied to a particular instance, but rather the whole class.
-- `return Enemy.num_of_enemy` &rarr; provides the current value of `num_of_enemy`
-  - notice the `Enemy.` &rarr; tells Python this is a **class variable** of the `Enemy` class
+```{admonition} Code Explaination
+* `def get_num_of_enemy():` &rarr; this creates the method.
+  * It doesn’t have `self` because it’s not linked to one object; it works for the whole class.
+* `return Enemy.num_of_enemy` &rarr; this gives back the current number of enemies.
+  * The `Enemy.` part tells Python to use the **class variable** from the `Enemy` class.
+```
 
 ## Reduce Enemy Count
 
-So we have a count of the number of enemies, and we can retrieve that value, now we need to reduce the enemy count when the player defeats an enemy.
+We can now count how many enemies there are and check that number, but we also need to **lower** the count when the player beats an enemy.
 
-The `Enemy` class `fight` method already has code that is executed when the player defeats the enemy, so we just need to add to that.
+The `fight` method in the `Enemy` class already runs code when an enemy is defeated, so we just need to add one extra line there.
 
-Still in **character.py** go to insert the highlighted line below:
+Stay in **character.py** and add the highlighted line below.
 
 ```{code-block} python
 :linenos:
@@ -270,14 +276,16 @@ class Enemy(Character):
 
 Save the code before we **Investigate** it:
 
-- line `53` &rarr; already determines if the player beats the enemy
-- `Enemy.num_of_enemy -= 1` &rarr; reduces the value of the **class variable** by one.
+```{admonition} Code Explaination
+* Line `53` already checks if the player wins the fight.
+* `Enemy.num_of_enemy -= 1` makes the class variable go down by one when an enemy is defeated.
+```
 
 ## Check for Victory
 
-The player will be victorious when they have defeated all the enemies in the dungeon. When all the enemies have been defeated the `Enemy.num_of_emeny` will be `0`. So we need to find the best place to check this.
+The player wins the game when every enemy has been defeated. When that happens, `Enemy.num_of_enemy` will be `0`. So we need to choose the right spot in the code to check for this.
 
-Let's look back at **main.py**. Line `89` is where Python decides if they player wins, so it makes sense to put out `num_of_enemy` check around here.
+In **main.py**, line `89` is already where the game checks if the player wins, so that’s the best place to add our `num_of_enemy` check.
 
 Add the highlighted code below:
 
@@ -408,10 +416,12 @@ while running:
 
 **Investigating** that code:
 
-- line `89` &rarr; already established that our new code will only run when the player defeats an enemy
-- `if Enemy.get_num_of_enemy() == 0:` &rarr; checks if the **class variable** is `0`
-- `print("You have slain all the enemies. You are victorious!")` &rarr; displays a victory message
-- `running = False` &rarr; readies to finish the game by exiting the main loop.
+```{admonition} Code Explaination
+* Line `89` makes sure this code only runs after the player defeats an enemy.
+* `if Enemy.get_num_of_enemy() == 0:` checks if the class variable has reached `0`.
+* `print("You have slain all the enemies. You are victorious!")` shows the win message.
+* `running = False` stops the main loop so the game can end.
+```
 
 ## Testing
 

build/.doctrees/stage_7.doctree

@@ -1,32 +1,37 @@
 # Stage 8 - Useability
 
-```{topic} In this lesson you will:
-
-- Improve the code useabilty
+```{topic} Learning Intentions
+In this lesson you will:
+* understand why making something easy to use is important for the person using it
+* know what UI and UX mean and why they matter when people use a program
+* understand how comments and neat code make a program easier to read and fix
+* improve a program by adding features that help the user, like a help option or clearer messages
+* tidy up a program by removing code you don’t need and organising it so it’s easier to read and use
 ```
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/lHSCfn0U45k" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
 ## Introduction
 
-Our dungeon is complete. We have a fully functioning game, but before we sign-off we need to improve the useability of our program and tidy up our code.
+Our dungeon works, but before we finish we need to make it easier to use and clean up the code.
+
+We will:
 
-To do this we will:
+* add a **help** command
+* make the program easier to read and use
+* add a goodbye message at the end
+* write more comments in the code
+* delete code we don’t need
+* make our spacing neat and consistent
 
-- Create a **help** command
-- Improve the user experience and user interface
-- Add a farewell message
-- Add some in-code comments
-- Remove unused code
-- Standardise our white-space
 
 ## Help command
 
-We know all the commands we can use because we wrote the code. Someone else might not know what they can say. In addition, if they don't enter one of the commands, the program only says `I don't understand.`, which is far from helpful.
+We know the commands because we wrote the code. A new player won’t know what they’re allowed to type. Right now, if they type something wrong, the program just says “I don’t understand,” which isn’t very helpful.
 
-To make life easier for new players, we should create a **help** command which lists all the commands. But how will the player know about the **help** command, without using the **help** command? Simple, we change the catch-all event handler (under the `else:`) to inform the user about the help command.
+To fix this, we should add a **help** command that shows all the commands. But players won’t know the help command exists unless we tell them. So we update the final `else:` section to remind them to type “help” when they get something wrong.
 
-To implement this, add the highlighted code below to **main.py**:
+Now add the highlighted code to **main.py**.
 
 ```{code-block} python
 :linenos:
@@ -161,23 +166,25 @@ while running:
         print("Enter 'help' to list the copmmands.")
 ```
 
-By now this code should be familiar and makes sense to you.
+You’ve seen this kind of code many times now, so you should already understand how it works without investigating it.
 
 ## Improving the UI and UX
 
-Although our program is visually very simple, the user stills interacts with it, which means we need to consider the UI and the UX.
+Even though our program looks simple, people still have to use it, so we need to think about the UI and UX &mdash; how it looks and how easy it is to use.
+
 
 ```{admonition} UI and UX
-UI stands for User Interface, which is basically what you see on your screen when you use an app or a website. This includes things like buttons, menus, icons, and colors. UI design focuses on making things look good and easy to use.
+:class: note
+UI means **User Interface**. It’s the stuff you actually see on the screen when you use an app or website — things like buttons, menus, icons, and colours. UI is about making everything look clear and easy to use.
 
-UX stands for User Experience, which is how you feel when you use an app or a website. It's about how easy it is to use, how it makes you feel, and whether it helps you achieve what you're trying to do. UX design focuses on making things easy and enjoyable to use.
+UX means **User Experience**. It’s about what it *feels* like to use the app — if it’s easy, confusing, fun, or annoying. UX is about making sure the user has a smooth and enjoyable time using the program.
 ```
 
-We have already addressed some UI and UX problems by adding the **help** command. Play the game and see if you can identify anything else.
+We’ve already fixed some UI and UX issues by adding the **help** command. Now play the game and see if you can spot anything else that feels confusing.
 
-Did you notice that after entering a command, the game responds and then quickly describes the room again. It's really easy to loose the command response in this quick action. Let's change that by writing the response and then asking the user to press a key to proceed.
+You might notice that after you type a command, the game shows the response and then instantly prints the room description again. This makes it easy to miss what the game just told you. To fix that, we’ll show the response and then make the user press a key before the game continues.
 
-I implement this, add the highlighted code below.
+To do this, add the highlighted code below.
 
 ```{code-block} python
 :linenos:
@@ -317,16 +324,18 @@ Save the file, **predict** and then **run** the code.
 
 How does that work? Let's **investigate**:
 
-- `input("\nPress <Enter> key to continue")` &rarr; this is a hack. That is we are using `input` in an unconventional way to achieve our desired outcome.
-  - the normal operation of `input` is to wait for the user response &rarr; addresses the pausing of the game
-  - normally the user enters their response by pressing the Enter key &rarr; stops the pausing
-  - the value the user enters is **not** assigned to a variable, so it just disappears
+```{admonition} Code Explaination
+* `input("\nPress <Enter> key to continue")` is basically a little trick. We’re using `input` in a way it’s not normally meant to be used.
+  * Normally, `input` waits for the user to type something, which is why it pauses the game.
+  * The user presses **Enter** to continue, which ends the pause.
+  * We don’t save what the user types, so whatever they enter is ignored and disappears.
+```
 
 ## Farewell message
 
-When the game ends, it just stops. Whether the player won or lost it just exits the the Shell prompt. To make things a little more polite, we should add an farewell message.
+When the game ends, it just shuts off straight away. No message, even if you win or lose. To make the ending feel a bit nicer, we should add a goodbye message.
 
-To include a farewell message add the highlighted code below
+Add the highlighted code below to include the farewell message.
 
 ```{code-block} python
 :linenos:
@@ -465,7 +474,13 @@ print("Thank you for playing Deepest Dungeon")
 
 ## In-code comments
 
-We already have some in-code comment that helps structure our code, but we have missed much of the main loop. We should add some comment to the main loop to make our code more readable and therefore maintainable.
+We already have a few comments in the code to help explain what parts do, but most of the main loop doesn’t have any. Adding comments there will make the code easier to read and easier to fix later.
+
+
+```{admonition} Code maintainability
+:class: note
+Code maintainability means making your code easy to understand, fix, and update later. If your code is neat, well-organised, and has clear comments, you or someone else can quickly figure out how it works. This makes it easier to find bugs, add new features, and change things without breaking the program.
+```
 
 Let's first start with **main.py**
 
@@ -613,7 +628,7 @@ while running:
 print("Thank you for playing Deepest Dungeon")
 ```
 
-When you create classes your should really have a comment that explains what each method does. If you look at the classes in our **room.py**, **item.py** and **character.py** files you will see that we have already done this.
+When you make classes, it’s a good idea to add a comment explaining what each method does. If you check the classes in **room.py**, **item.py**, and **character.py**, you’ll see we’ve already done this there.
 
 ## Remove unused code
 
@@ -764,7 +779,7 @@ print("Thank you for playing Deepest Dungeon")
 
 ## Final code
 
-White space is the blank lines between our code. You can use this to help structure your code.
+Whitespace is the empty lines in your code. You can use it to break your code into clear sections and make it easier to read.
 
 Finalise your code by adjusting it so to look the same as the following code:
 
@@ -1035,8 +1050,8 @@ class Item():
 
 ## Final Make
 
-The tutorials are now over. It is time to make this dungeon yours by adding new features. The Extensions Ideas page has some suggestions.
+The tutorials are finished. Now it’s your turn to make the dungeon your own by adding new features. You can check the Extension Ideas page for inspiration.
 
-The current code does have a couple of logical errors, but you will have to test it to find out what they are and then try and solve them. Don't forget to use your debugger to help you with this.
+There are a few logic mistakes in the code, but you’ll need to test the game to find them and work out how to fix them. Make sure you use your debugger to help.
 
-Good luck. May your adventure be long and fruitful.
+Good luck on your adventure.