From eaa527f04dbb5636f5648fee3bef4de30532cd86 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 09:49:57 -0400 Subject: [PATCH 1/7] first change to test --- doc/tutorials/platform_tutorial/step_01.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorials/platform_tutorial/step_01.rst b/doc/tutorials/platform_tutorial/step_01.rst index db74cdedeb..b887d6b13e 100644 --- a/doc/tutorials/platform_tutorial/step_01.rst +++ b/doc/tutorials/platform_tutorial/step_01.rst @@ -14,7 +14,7 @@ Installation * Make sure the `Arcade library `_ is installed. - * You should first setup a virtual environment (venv) and activate it. + * You should first setup a virtual environment (venv) and activate it. This is hard. * Install Arcade with ``pip install arcade``. * Here are the longer, official :ref:`install`. From b3d12dd63b140eb37f6f2e287453044f2da4c854 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 10:07:32 -0400 Subject: [PATCH 2/7] condense install section --- doc/tutorials/platform_tutorial/step_01.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/doc/tutorials/platform_tutorial/step_01.rst b/doc/tutorials/platform_tutorial/step_01.rst index b887d6b13e..87f53a5543 100644 --- a/doc/tutorials/platform_tutorial/step_01.rst +++ b/doc/tutorials/platform_tutorial/step_01.rst @@ -9,14 +9,8 @@ get a window open. Installation ~~~~~~~~~~~~ -* Make sure Python is installed. `Download Python here `_ - if you don't already have it. - -* Make sure the `Arcade library `_ is installed. - - * You should first setup a virtual environment (venv) and activate it. This is hard. - * Install Arcade with ``pip install arcade``. - * Here are the longer, official :ref:`install`. +* For any of this to work, you need Python with the Arcade module. +Instructions for that are here: :ref:`install`. Open a Window ~~~~~~~~~~~~~ From 3f78e894221aa4ceefc0d7e41ce6d9279ff00aa0 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 10:16:22 -0400 Subject: [PATCH 3/7] condense install section - format 2 --- doc/tutorials/platform_tutorial/step_01.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/tutorials/platform_tutorial/step_01.rst b/doc/tutorials/platform_tutorial/step_01.rst index 87f53a5543..d6bccc8fac 100644 --- a/doc/tutorials/platform_tutorial/step_01.rst +++ b/doc/tutorials/platform_tutorial/step_01.rst @@ -9,8 +9,9 @@ get a window open. Installation ~~~~~~~~~~~~ -* For any of this to work, you need Python with the Arcade module. -Instructions for that are here: :ref:`install`. +For any of this to work, you need Python with the Arcade module installed. + +* Instructions for that are here: :ref:`install`. Open a Window ~~~~~~~~~~~~~ From 440d4df3046a5afa25ae30addc9b1187a33edee7 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 11:26:57 -0400 Subject: [PATCH 4/7] testing an external link --- doc/_archive/install/windows.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/_archive/install/windows.rst b/doc/_archive/install/windows.rst index 08e40885bc..1fb69c274c 100644 --- a/doc/_archive/install/windows.rst +++ b/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 `_ Step 1: Install Python ---------------------- From 0c45880f72c378dcd3ed8d10f24118f5a7b08175 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 18:42:32 -0400 Subject: [PATCH 5/7] install and step 1 finalized --- .pre-commit-config.yaml | 2 +- doc/get_started/install.rst | 7 ++ doc/tutorials/platform_tutorial/step_01.rst | 112 +++++++++++++++++--- 3 files changed, 103 insertions(+), 18 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dd6633f90d..d71f581fff 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/doc/get_started/install.rst b/doc/get_started/install.rst index 5733fcf709..34c8e7223d 100644 --- a/doc/get_started/install.rst +++ b/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 `_ + Requirements ------------ Arcade requires a desktop, laptop, or compatible Single-Board Computer (SBC) with: diff --git a/doc/tutorials/platform_tutorial/step_01.rst b/doc/tutorials/platform_tutorial/step_01.rst index d6bccc8fac..c1de14c1a2 100644 --- a/doc/tutorials/platform_tutorial/step_01.rst +++ b/doc/tutorials/platform_tutorial/step_01.rst @@ -4,20 +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 ~~~~~~~~~~~~ For any of this to work, you need Python with the Arcade module installed. -* Instructions for that are here: :ref:`install`. +* 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. + +.. code-block:: + + python -m arcade.examples.platform_tutorial.01_open_window + +You should end up with a window like this: -Open a Window -~~~~~~~~~~~~~ +.. image:: step_01.png + :width: 75% -The example below opens up a blank window. Set up a project and get the code -below working. +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:: @@ -26,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: @@ -46,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. From 95dbda8b8f917047cdde570be584663f65d51558 Mon Sep 17 00:00:00 2001 From: Dickerson Date: Mon, 19 May 2025 22:05:13 -0400 Subject: [PATCH 6/7] step_02 done --- doc/tutorials/platform_tutorial/step_02.rst | 105 +++++++++++++------- 1 file changed, 70 insertions(+), 35 deletions(-) diff --git a/doc/tutorials/platform_tutorial/step_02.rst b/doc/tutorials/platform_tutorial/step_02.rst index f0b1ae3ee0..ccd15f978d 100644 --- a/doc/tutorials/platform_tutorial/step_02.rst +++ b/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 From e5080701763eb737c8fe321c20a47963bf5ae33a Mon Sep 17 00:00:00 2001 From: Dickerson Date: Tue, 20 May 2025 09:22:30 -0400 Subject: [PATCH 7/7] fixing ~~~ thing --- doc/tutorials/platform_tutorial/step_01.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorials/platform_tutorial/step_01.rst b/doc/tutorials/platform_tutorial/step_01.rst index c1de14c1a2..d28e0eb9cd 100644 --- a/doc/tutorials/platform_tutorial/step_01.rst +++ b/doc/tutorials/platform_tutorial/step_01.rst @@ -44,7 +44,7 @@ this going, you have succeeded in what is generally the hardest part of any new 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