Optional update for the platform tutorial.

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 default_language_version:
-  python: python3.10
+  python: python3.13
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks

doc/_archive/install/windows.rst

@@ -2,7 +2,10 @@ Windows
 =======
 
 To develop with the Arcade library, we need to install Python, then install
-Arcade.
+Arcade. If you are comfortable setting things up and know how to run a
+command prompt, this is a decent guide to setting things up. If the idea
+of a virtual environment is new, a better guide for setting up Python is 
+here: `Your Python Coding Environment on Windows: Setup Guide <https://realpython.com/python-coding-setup-windows/>`_
 
 Step 1: Install Python
 ----------------------

doc/get_started/install.rst

@@ -8,6 +8,13 @@ Install
 
 .. _install_requirements:
 
+.. note:: These steps require some basic computer admin knowledge.
+
+    If you are comfortable installing programs and know how to run a
+    command prompt, this is a decent guide to setting things up. If the idea
+    of a virtual environment is new, a better guide for setting up Python is
+    here: `Your Python Coding Environment on Windows: Setup Guide <https://realpython.com/python-coding-setup-windows/>`_
+
 Requirements
 ------------
 Arcade requires a desktop, laptop, or compatible Single-Board Computer (SBC) with:

doc/tutorials/platform_tutorial/step_01.rst

@@ -4,25 +4,36 @@
 Step 1 - Install and Open a Window
 ----------------------------------
 
-Our first step is to make sure everything is installed, and that we can at least
-get a window open.
+You will do two things in this section.
+
+1) Run the code from the arcade module directly. This will open a simple window.
+
+2) Create your own file with the copied code to work on for the rest of the tutorial.
+   Run it, you will get the same window, but THIS copy you control!
 
 Installation
 ~~~~~~~~~~~~
-* Make sure Python is installed. `Download Python here <https://www.python.org/downloads/>`_
-  if you don't already have it.
+For any of this to work, you need Python with the Arcade module installed.
+
+* Setup instruction are here: :ref:`install`.
+
+Verify the Installation (Step 1)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run the following code from a terminal in the folder that contains the arcade directory.
 
-* Make sure the `Arcade library <https://pypi.org/project/arcade/>`_ is installed.
+.. code-block::
 
-  * You should first setup a virtual environment (venv) and activate it.
-  * Install Arcade with ``pip install arcade``.
-  * Here are the longer, official :ref:`install`.
+  python -m arcade.examples.platform_tutorial.01_open_window
 
-Open a Window
-~~~~~~~~~~~~~
+You should end up with a window like this:
 
-The example below opens up a blank window. Set up a project and get the code
-below working.
+.. image:: step_01.png
+   :width: 75%
+
+The window is pretty useless... You can minimize it and even close it! However, if you got
+this going, you have succeeded in what is generally the hardest part of any new project
+- getting the environment setup! Congratulations! (Commence party dance sequence!)
 
 .. note::
 
@@ -31,14 +42,78 @@ below working.
   interesting things we can do first. Therefore we'll stick with a fixed-size
   window for this tutorial.
 
+
+Coding...The fun part! (Step 2)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You also need a code editor. There are dozens of options and we can't keep up with them
+here. A simple text editor could work, but better options abound. A web search is your
+friend - search for "Python editor" and pick one that looks good. Visual Studio Code
+(VS Code) is a nice free option. PyCharm is another.
+
+
+* Open your editor of choice and make a new file, call it main.py (the name is important!)
+* Copy this code into it.
+
 .. literalinclude:: ../../../arcade/examples/platform_tutorial/01_open_window.py
     :caption: 01_open_window.py - Open a Window
     :linenos:
 
-You should end up with a window like this:
+* Run the code from the same environment and in the folder with the code:
 
-.. image:: step_01.png
-   :width: 75%
+.. code-block::
+
+  python main.py
+
+What is this code?
+~~~~~~~~~~~~~~~~~~
+
+Explaining in depth every part of the code would be tedious and pretty overwhelming,
+and ultimatly not the most useful way to learn. But knowing the intent of sections is good!
+
+Comments
+    Triple quotations mark the begin and end of comments - sections of
+    code that the computer ignores. It is for us humans!
+    A second way of making a comment is the '#' symbol which lets python know to
+    ignore everything on that line after the symbol.
+
+import arcade
+    This tells python which tools it needs to use to run the code. The magic sauce that does
+    all the heavy lifting for the program so that you can focus on being creative!
+
+# Constants section
+    Remember how we said the window is a fixed size? Can you guess WHAT size it is fixed to
+    from these lines? Did you notice a title on the window (go ahead and peek!).
+
+class GameView(arcade.Window):
+    Classes are extremely important programming concepts. In simple terms, it is a collection
+    of data that you do things with. It keeps things organized!
+
+def __init__(self):
+    Data sets that make up class objects need initial information. You provide that here.
+
+def setup(self):
+    pass? what are we passing? Well, nothing, this is a place holder for future awesome code.
+    pass tells Python that the function does nothing at the moment and it can move along.
+
+def on_draw(self):
+    Right now this function runs a simple command - self.clear(). Notice all the comments! That
+    is so that you (the coder) knows what is going on in the function. More on this section to follow!
+
+def main():
+    This is the entry point for Python. When you run a program, Python looks for a main() function
+    and runs it. Then three steps happen:
+
+1) window = GameView() -> Your window object is created. Your __init__ function is automatically called.
+2)  window.setup() - > You run the window object's setup function... Which does nothing at the moment (pass!)
+3) arcade.run() -> You turn on the engine and see the results. The program stays here until the
+   window is closed. Then with nothing else to do, the program will terminate.
+
+if __name__ == "__main__":
+    If Python was run by starting this file in particular, then its "__name__" value will be "__main__".
+    And the main() function will be called. Remember how we said the name of the file was important?
+
+Challenge Exercises
+~~~~~~~~~~~~~~~~~~~
 
 Once you get the code working, try figuring out how to adjust the code so you can:
 
@@ -51,10 +126,8 @@ Once you get the code working, try figuring out how to adjust the code so you ca
 
 * Look through the documentation for the :class:`arcade.Window`
   class to get an idea of everything it can do.
-
-Run This Chapter
-~~~~~~~~~~~~~~~~
-
-.. code-block::
-
-  python -m arcade.examples.platform_tutorial.01_open_window
+* Break it! Yes this sounds bad, but comment out some sections of the code and try to run it.
+  You will make mistakes and this can help you get familure with error messages. Also, see if
+  you can see in the error message WHERE the problem exists or other such clues. You already
+  know because you made them... Make sure you save the good code and it is functional again
+  before moving on.

doc/tutorials/platform_tutorial/step_02.rst

@@ -3,31 +3,46 @@
 Step 2 - Textures and Sprites
 -----------------------------
 
-Our next step in this tutorial is to draw something on the Screen. In order to
-do that we need to cover two topics, Textures and Sprites.
+Our next step in this tutorial is to draw something on the Screen.
 
-At the end of this chapter, we'll have something that looks like this. It's largely the
-same as last chapter, but now we are drawing a character onto the screen:
+To see what we will accomplish, run this code:
+
+.. code-block::
+
+  python -m arcade.examples.platform_tutorial.02_draw_sprites
+
+
+You should see the same window, but now with a character on the screen:
 
 .. image:: images/title_02.png
     :width: 70%
 
+Images in 2D games are created using Textures and Sprites. Let's discuss those ideas.
+
 Textures
 ~~~~~~~~
 
 Textures are largely just an object to contain image data. Whenever you load an image
-file in Arcade, for example a ``.png`` or ``.jpeg`` file. It becomes a Texture.
+file in Arcade, for example a ``.png`` or ``.jpeg`` file, it becomes a Texture.
 
 To do this, internally Arcade uses Pyglet to load the image data, and the texture is
 responsible for keeping track of this image data.
 
 We can create a texture with a simple command, this can be done inside of our ``__init__``
-function. Go ahead and create a texture that we will use to draw a player.
+function. Go ahead and create a texture that we will use to draw a player by adding this code
+into the __init__ function of the GameView class. Right below the "super()..." statement is fine.
 
 .. code-block::
 
     self.player_texture = arcade.load_texture(":resources:images/animated_characters/female_adventurer/femaleAdventurer_idle.png")
 
+What is the code doing?
+    the 'self.' part the of statement officially attaches the stuff that comes behind it to become part
+    of the class it is attached to. In this case, ANY function inside GameView now has access to a
+    variable self.player_texture. That is how we 'share' the class data with the class methods (functions).
+    arcade.load_texture() does all the dirty work of accepting a path to a image file and making it
+    useful for the program.
+
 .. note::
 
     You might be wondering where this image file is coming from? And what is ``:resources:`` about?
@@ -46,12 +61,15 @@ function. Go ahead and create a texture that we will use to draw a player.
 Sprites
 ~~~~~~~
 
-If Textures are an instance of a particular image, then :class:`arcade.Sprite` is an instance of that image
-on the screen. Say we have a ground or wall texture. We only have one instance of the texture, but we can create 
-multiple instances of Sprite, because we want to have many walls. These will use the same texture, but draw it
-in different positions, or even with different scaling, rotation, or colors/post-processing effects.
+While the texture data is now 'saved' into the class as a variable. We can't use it as is, we need to convert it
+to a Sprite. If Textures are an instance of a particular image from a file, then :class:`arcade.Sprite` is an
+instance of that image that can be put on the screen later on. Say we have a ground or wall texture. We only have
+one instance of the texture, but we can create multiple instances of Sprite, because we want to have many walls.
+These will use the same texture, but draw it in different positions, or even with different scaling, rotation,
+or colors/post-processing effects.
 
-Creating a Sprite is simple, we can make one for our player in our ``__init__`` function, and then set it's position.
+Creating a Sprite is simple, we can make one for our player in our ``__init__`` function. Make sure it is
+right after the previous statement. See the challenge section for why this is important!
 
 .. code-block::
 
@@ -61,16 +79,54 @@ Creating a Sprite is simple, we can make one for our player in our ``__init__``
 
 .. note::
 
-    You can also skip ``arcade.load_texture`` from the previous step and pass the image file to ``arcade.Sprite`` in place of the Texture object. 
+    You can also skip ``arcade.load_texture`` from the previous step and pass the image file to ``arcade.Sprite`` in place of the Texture object.
     A Texture will automatically be created for you. However, it may desirable in larger projects to manage your textures directly.
 
-Now we can draw the sprite by adding this to our ``on_draw`` function:
+
+Rendering
+~~~~~~~~~
+
+If you ran your program as is, you will notice.... nothing new! We have simply given the class a
+texture and defined a sprite. But no instructions on what to do with that data. Remember, classes are objects
+that HAVE data (our image in sprite-form now) and DO stuff with the data.
+
+Rendering is how we get our cool Sprite onto our window by adding the next command to our ``on_draw`` function. Place it under the
+"# Code to draw other things will go here" comment.
 
 .. code-block::
 
+    # Code to draw other things will go here
     arcade.draw_sprite(self.player_sprite)
 
-We're now drawing a Sprite to the screen! In the next chapter, we will introduce techniques to draw many(even hundreds of thousands) sprites at once.
+Now run the code! You will have to remember the code to run your program from now on :)
+
+.. code-block::
+
+  python main.py
+
+Challenge
+~~~~~~~~~
+
+* Play with the center_x and center_y variables - what do they do?
+* Move the load.texture statement after the arcade.Sprite(self.player_texture) statement and run it.
+  It fails. Why? Well, its because computers do things in order. If you try to use a variable before
+  defining it, you will get an error. Computers don't try to guess what you want or bother looking
+  around for the item. If it is not there, it instantly gives up.
+* See if you can find the location of the resources and use a different image file.
+* use a loop to create several copies of the image to the window - each with different locations. Hint:
+  add the 'import random' module (another toolbox for Python) right under the import arcade statement.
+  With the random module you can use random.randint(X, Y) which will give a random number between
+  X and Y (including possibly X and Y).
+* EXTREME challenge - make your own image file - even a stick figure! And use that instead. paint.net
+  is a good free option. aseprite.org is a low cost option and esotericsoftware.com has Spine for a
+  more expensive option. MANY others exist. Don't spend too much time on this though :) Just enough to
+  get your creative juices flowing! Maybe just use a picture of your face!
+* Explore the documentation for the :class:`arcade.Texture` class
+* Explore the documentation for the :class:`arcade.Sprite` class
+
+Once you are finished with any or all challenges - make sure your code matches this so that future
+tutorial steps still work! Feel free to comment out sections of custom code you want to keep playing
+with later.
 
 Source Code
 ~~~~~~~~~~~
@@ -79,24 +135,3 @@ Source Code
     :caption: 02_draw_sprites - Draw and Position Sprites
     :linenos:
     :emphasize-lines: 24-30, 44-45
-
-Running this code should result in a character being drawn on the screen, like in
-the image at the start of the chapter.
-
-* Documentation for the :class:`arcade.Texture` class
-* Documentation for the :class:`arcade.Sprite` class
-
-.. note::
-
-    Once you have the code up and working, try adjusting the code for the following:
-
-    * Adjust the code and try putting the sprite in new positions(Try setting the positions using other attributes of Sprite)
-    * Use different images for the texture (see :ref:`resources` for the built-in images, or try using your own images.)
-    * Practice placing more sprites in different ways(like placing many with a loop)
-
-Run This Chapter
-~~~~~~~~~~~~~~~~
-
-.. code-block::
-
-  python -m arcade.examples.platform_tutorial.02_draw_sprites