diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index 0f30b0db5..3178585f3 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -223,7 +223,10 @@ table.resource-table td { } table.resource-table td > img { display: inline-block; + /* Maximum 20% of the smallest display dimension */ + max-width: min(20vw, 20vh); } + table.colorTable { border-width: 1px; } diff --git a/doc/about/faq.rst b/doc/about/faq.rst index fee1ee756..0a1ca73c9 100644 --- a/doc/about/faq.rst +++ b/doc/about/faq.rst @@ -1,29 +1,96 @@ +.. _faq: Frequently asked questions ========================== -Can I copy and adapt example code for my own projects? ------------------------------------------------------- +.. _faq_education: + +Can I use Arcade resources in my own educational materials? +----------------------------------------------------------- -Of course. You can copy and adapt example code for your own projects for any reason. -In fact, we encourage you to do so. We want you to learn and be successful. +.. _gh_license: https://github.com/pythonarcade/arcade/blob/development/license.rst -Can Arcade run on the web? --------------------------- +Yes! Arcade was originally developed for educational use. In addition to +a page :ref:`academia`, we have further documentation covering: -Currently Arcade projects cannot easily be build to run on the web. -It can be possible in the future but will require a lot of work -in pyglet, the underlying library that Arcade uses. + +* The :ref:`permissive_mit` covers the library and documentation +* The :ref:`CC0 Public Domain Dedication ` and similar cover the :ref:`resources` + +.. _faq_commercial: Can I use Arcade in a commercial project? ----------------------------------------- -Of course. Arcade is released under the MIT License. This means you can use it for free. -Even adapted versions of Arcade or parts of it can be used in commercial projects. +:ref:`commercial_games`. There's already one commercially released game using Arcade. -Can I use Arcade resources in my own educational materials? ------------------------------------------------------------ +.. _faq-copying: + +Can I copy and adapt example code for my own projects? +------------------------------------------------------ + +Of course! We encourage you to do so. That's why the example code is there: we +want you to learn and be successful. See the :ref:`permissive_mit` section to learn +more about Arcade's license means (you agree not to claim you wrote the whole thing). + +Can Arcade run on...? +--------------------- + +Windows, Mac, and Linux +^^^^^^^^^^^^^^^^^^^^^^^ + +Yes. Most hardware with an Intel or AMD processor from the last ten years will do fine. +New :ref:`requirements_mac_mseries` can have some hiccups, but they generally work. + +.. _faq-raspi: + +Raspberry Pi and Other SBCs +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Raspberry Pi is a popular brand of Single Board Computers (SBCs). + +The Raspberry Pi 4 and 5 can run Arcade under `Raspberry Pi OS`_, +and the Raspberry Pi 400 *may* also work. As of October 2024, +:ref:`All other other Raspberry Pi models are incompatible `. + +Other SBCs *may* work with Arcade 3.0.0. See the :ref:`sbc_requirements` to learn more. + +.. _faq_web: + +Web +^^^ +Not yet. For the moment, the Arcade and `pyglet`_ teams are eagerly +watching ongoing developments in `WebGPU`_ and its `WASM`_ integrations. + +.. _WebGPU: https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API +.. _WASM: https://developer.mozilla.org/en-US/docs/WebAssembly + +.. _faq_mobile: + +Mobile +^^^^^^ +Not in the near future. Supporting mobile requires big changes to both +Arcade and the `pyglet`_ library we use. + +.. _faq_android: + +Android +""""""" +Android support will take a huge amount of work: + +#. `pyglet`_ would need to account for mobile-specific OS behavior +#. Arcade would need to make changes to account for mobile as well +#. Not all devices will support the necessary :ref:`OpenGL ES versions `. + +.. _faq_ios: +.. _faq_ipad: + +iOS and iPad +"""""""""""" + +Not in the foreseeable future. They are much trickier than web or Android +for a number of reasons. For near-future iOS and iPad support, you may want to +to try `Kivy`_. + +.. _Kivy: https://kivy.org -Of course! Arcade was built to support learning. -You can use its materials however you need— -whether you stick with the original content or make changes to suit your needs. diff --git a/doc/about/for_academia.rst b/doc/about/for_academia.rst new file mode 100644 index 000000000..1eb5811a2 --- /dev/null +++ b/doc/about/for_academia.rst @@ -0,0 +1,166 @@ +.. _academia: + +For Educators & Researchers +=========================== + +.. _citation template: https://github.com/pythonarcade/arcade#citation + +Python Arcade was created by Paul V. Craven while teaching at Simpson College. + +In addition to the main Arcade 3.0 documentation you are currently reading, there +are further resources to help academic users. These include: + +* The :ref:`citation template ` +* A companion :ref:`academia_arcade_book` by Arcade's creator +* Potential 2.6.X maintenance releases to support curricula using Arcade 2.6 + + +.. _academia_citations: + +Citation Template +----------------- + +Arcade provides a `citation template`_ in `BibTeX`_ format. + +To learn more about using this template, please consult the following: + +* the documentation of your reference management tool +* any style guides you are required to follow + + +.. _academia_version_2v3: + +Version Considerations +---------------------- +Most users will be better off using Arade 3.0. + +The main case for continuing to use ``2.6.X`` releases is reliance on teaching +materials which have not yet been updated, including the :ref:`academia_arcade_book`. + + +.. _academia_arcade_book: + +Arcade Book +^^^^^^^^^^^ + +The creator of Arcade wrote an `Arcade book`_ which covers Python basics in greater depth +than the main Arcade documentation. + + +It may be some time until the `Arcade book`_ is updated for Arcade 3.0. Doing so requires a +separate effort after the 3.0 release due to the the scale and number of changes since +Arcade 2.6. + + +Similarities to this Documentation +"""""""""""""""""""""""""""""""""" + +Both the book and the documentation you are currently reading provide: + +* all-ages learning resources +* gentle introductions to Python and Arcade + + +Differences from this Documentation +""""""""""""""""""""""""""""""""""" + +The book caters more heavily to beginners and educators by providing the following +in a traditional chapter and curriculum structure: + +#. Embedded videos covering concepts and past student projects +#. Lab exercises to help apply chapter material through practice +#. Translations in `Swedish / Svenska `_ and `German / Deutsche `_ + +It also offers gentle, beginner-friendly introductions to topics which can intimidate +even the graduates of college-level computer science programs: + +#. Editors and development environments +#. Industry-standard version control tools +#. CS topics applicable at college-level and beyond + + +.. _2_6_maintenance: + +2.6.X Maintenance? +------------------ + +The Arcade team is exploring additional *maintenance-only* releases for 2.6.X. + +The goals for these still-hypothetical releases would be: + +#. Security updates +#. Compatibility with newer Python versions +#. Highly limited bug fixes + +Since the Arcade team's focus is on improving Arcade 3.0, no new features will be added +unless at least one of the following is true: + +* It is required for a security or compatibilty improvement +* The effort required is minimal + + +Raspberry Pi and other SBCs +--------------------------- + +For educators, Single-Board Computers (SBCs) such as the Raspberry Pi 4 and 5 +are not always the most cost-effective option. + +However, they may be an attractive option when at least one of the following +applies: + +* You have an educational discount +* You have grant or non-profit funding +* Surplus hardware isn't an option + + +.. _sbc_rule_of_thumb: + +SBC Purchasing Rules of Thumb +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: These rules help **non-experts** steer toward Arcade-copatible devices. + + You can find more in-depth descriptions of the required OpenGL ES versions + and more under the :ref:`sbc_requirements` heading. + + +ARM64 and AMD64 are Easiest +""""""""""""""""""""""""""" + +The :ref:`known-working Raspberry Pi 4 and 5 ` are both ARM64 +devices. If you are considering other boards due to price or availability, stick to +the following CPU architectures: + +* ARM64 +* AMD64 (same as most non-Mac desktop CPUs) + +No RISC-based SBC has been verified as compatible. Although some *may* work, +SBCs based on RISC-V CPUs are likely to lack: + +* introductory tutorials +* beginner-friendly documentation + + + +Credit Card Rule +"""""""""""""""" + +As of October 2024, all compatible and widely-available SBCs are +larger than credit cards: + +* 3.375 inches by 2.125 inches +* 85.60 mm by 53.98 mm + +If you try to use this rule: + +#. Compare to the actual circuit board's size, not the size of the package +#. Use an old hotel key card, expired credit card, or expired debit card + +It's unlikey that an SBC board will have magnets. However, the package +might include them in motors (in kits) or as part of the box itself. +Using an old card stops you from accidentally wiping a magnetic strip you need. + +Although this errs on the side of caution, it also: + +* quickly rules out :ref:`incompatible Raspberry Pi models ` +* should apply to other SBCs as well diff --git a/doc/about/intro.rst b/doc/about/intro.rst index f06015a6b..47ebea078 100644 --- a/doc/about/intro.rst +++ b/doc/about/intro.rst @@ -2,20 +2,30 @@ Introduction ============ -Welcome to the official documentation of Arcade. +.. _intro_learning_resources: Learning Resources ------------------ -Arcade offers several resources to help you get started regardless of your -experience level. People learn in different ways, so we try to offer a variety -of resources to help you learn. +Arcade provides documentation for different experience levels and +learning styles. -* Examples -* Tutorials -* API Reference -* Arcade Book -* Skill Tree +Getting Started +^^^^^^^^^^^^^^^ + +* The :ref:`skill_tree` is a suggested learning order for beginners +* The :ref:`main-page-tutorials` are guided introductions to new skills +* The :ref:`example-code` help tinkerers get started quickly +* The manual in the left-hand sidebar has overviews of concepts and features + +Experienced Developers +^^^^^^^^^^^^^^^^^^^^^^ + +For more experienced developers, Arcade provides two forms of +API documentation: + +* The :ref:`arcade-api` follows Arcade's module layout and features +* The :ref:`quick_index` is a single-page search tool Community driven ---------------- diff --git a/doc/about/permissive_licensing.rst b/doc/about/permissive_licensing.rst new file mode 100644 index 000000000..7291115f1 --- /dev/null +++ b/doc/about/permissive_licensing.rst @@ -0,0 +1,119 @@ +.. _permissively_licensed: + +Freedom to Remix and Share +========================== + +Arcade makes sure you are free to build and share without worrying about fees or licenses. + +All parts of the library are available free of charge and without +complicated red tape: + +* Arcade's code uses the widely-adopted commercial-friendly + :ref:`MIT License ` +* The :ref:`resources` are high-quality and don't require attribution + +.. _commercial_games: + +Yes, You Can Make Commercial Games! +----------------------------------- + +There is already a commercially available game made with Arcade. + +`Spelly Cat`_ is a puzzle game available via Valve Software's `Steam marketplace `_. +It is currently available for Windows and Linux. + +.. important:: Arcade is currently a desktop-focused framework. + + :ref:`Web `, :ref:`Android `, :ref:`iPad `, + and :ref:`iOS ` are not currently supported. + +How Do I Publish My Games? +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It takes require patience, experimentation, and persistence. + +You will need to tinker with packaging and platform-specific application signing +approaches in addition to gameplay. The following tutorials and documentation will +help you get started on bundling: + +* :ref:`compile_with_nuitka` +* :ref:`bundle_into_redistributable` +* :ref:`resource_handles_one_file_builds` + +You will also need to consult the platform documentation for any app store and achievements +tracker you use. + +.. tip:: Even the Arcade maintainers have trouble with this! + + If you get stuck or frustrated, that's okay. Breathe deep, and remember + that you can always :ref:`politely ask for help `. + +.. _Spelly Cat: https://store.steampowered.com/app/2445350/Spelly_Cat/ +.. _Steam: https://store.steampowered.com/games/ + +.. _permissive_mit: + +The MIT License +--------------- + +In addition to the ``arcade`` package on `PyPI`_, the source code +is available for modification and :ref:`contributions ` +under the `OSI-Approved MIT License`_. Roughly speaking, that means +using Arcade is an agreement to the following: + +* You won't claim you wrote the whole library yourself +* You understand Arcade's features may have bugs + +.. tip:: If you see a bug or a typo, we love :ref:`contributing-bug-reports`. + +For more information on the MIT license, please see the following for a quick intro: + +* https://www.tldrlegal.com/license/mit-license +* https://choosealicense.com/licenses/mit/ + +.. _OSI-Approved MIT License: https://opensource.org/license/mit + +.. _permissive_almost_all_public: + +Public Domain Assets +-------------------- + +Arcade's :ref:`resources` are carefully hand-picked to meet three criteria: + +* High quality +* Friendly style +* Public domain (or as close as possible) + +This means that unless you're in Academia, you don't have to worry. The licenses and attribution +are all taken care of since we only ship built-in resources which minimize the requirements for you. +If something requires special handling, we'll warn you about it. + +Where are all these assets from? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Mostly from `Kenney.nl `_. Kenny is famous for creating a repository of free, high-quality +`CC0`_ (public domain) game assets. His work is funded by donations and +`Kenney's Patreon `_. + +Unlike other `Creative Commons licenses`_, the `CC0`_ doesn't impose terms or conditions. +It's the lawyer version saying the following: + +.. raw:: html + +
"I give permission to everyone to use this for whatever. Go make something cool!"
+ +Although Arcade includes a few bundled assets which aren't from `Kenny.nl `_, we've made sure +they're released under a similar license. + + +What About Academia? +-------------------- + +In addition to the MIT License, academics are expected to cite things. + +Don't worry, we've got that covered too. In fact, we have an entire page :ref:`academia`. +It covers crucial topics, such as: + +#. :ref:`academia_citations` +#. :ref:`academia_version_2v3` +#. :ref:`2_6_maintenance` diff --git a/doc/api_docs/images/fonts_blue.png b/doc/api_docs/images/fonts_blue.png new file mode 100644 index 000000000..284831d24 Binary files /dev/null and b/doc/api_docs/images/fonts_blue.png differ diff --git a/doc/community/community_locations.rst b/doc/community/community_locations.rst index 899c7e363..8b4691b0c 100644 --- a/doc/community/community_locations.rst +++ b/doc/community/community_locations.rst @@ -1,21 +1,40 @@ -.. include:: /links.rst - .. _community-locations: Community Locations =================== -Most of the community interaction happens on the `Arcade Discord`_ and `Arcade Github`_. -The discord server is the best place to ask questions and get help. -We have help channels, various topic channels, and a place to share -your projects. This is also where most of the development discussion -happens. +Community Standards +------------------- + +.. raw:: html + +
"Be excellent to each other"
+ +The Arcade community welcomes everyone from beginners to OpenGL experts. + +You should strive to uphold the following goals regardless of a +user's age or skill level: + +* Be kind by assuming good intentions +* Be patient, especially with beginners +* Be respectful of others + +Where to Post +------------- + +Most community activity is in one of two places: + +* The `Arcade Discord`_ server is the most active spot +* The `Arcade Github`_ repository hosts code and issues + +If you're unsure, the Discord is the best place to ask questions. +This includes changes such as new features, or just :ref:`getting help `. -Less active places (as of Summer 2024): +Other Locations +--------------- -* `Reddit`_ -* `Twitter`_ +Arcade has a presence on the platforms below, but they're not very active as +of Summer 2024: -Note that these communities have people of all ages from all around the -world. Please be respectful and kind to everyone. Assume good intentions -and be patient with people who are learning. +* `r/pythonarcadde `_ on Reddit +* `@ArcadeLibrary `_ on x.com (formerly Twitter) diff --git a/doc/community/how_to_get_help.rst b/doc/community/how_to_get_help.rst index 586d1fd18..94a458e87 100644 --- a/doc/community/how_to_get_help.rst +++ b/doc/community/how_to_get_help.rst @@ -1,5 +1,3 @@ -.. include:: /links.rst - .. _how-to-get-help: How to Get Help diff --git a/doc/conf.py b/doc/conf.py index fafb95b53..36ded5702 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -58,14 +58,14 @@ GIT_REF = VERSION log.info(f"Got real release: using {GIT_REF!r}") - # We'll pass this to our generation scripts to initialize their globals +FMT_URL_REF_BASE=f"{REPO_URL_BASE}/blob/{GIT_REF}" RESOURCE_GLOBALS = dict( GIT_REF=GIT_REF, BASE_URL_REPO=REPO_URL_BASE, # This double-bracket escapes brackets in f-strings - FMT_URL_REF_PAGE=f"{REPO_URL_BASE}/blob/{GIT_REF}/{{}}", - FMT_URL_REF_EMBED=f"{REPO_URL_BASE}/blob/{GIT_REF}/{{}}?raw=true", + FMT_URL_REF_PAGE=f"{FMT_URL_REF_BASE}/{{}}", + FMT_URL_REF_EMBED=f"{FMT_URL_REF_BASE}/{{}}?raw=true", ) def run_util(filename, run_name="__main__", init_globals=None): @@ -246,13 +246,16 @@ def run_util(filename, run_name="__main__", init_globals=None): # These will be joined as one block and prepended to every source file. # Substitutions for |version| and |release| are predefined by Sphinx. -rst_prolog = dedent(f""" - .. _Pymunk: https://www.pymunk.org/en/latest/index.html +PROLOG_PARTS = [ + #".. include:: /links.rst", + ".. |pyglet Player| replace:: pyglet :py:class:`~pyglet.media.player.Player`", + ".. _Arcade's License File on GitHub: {FMT_URL_REF_BASE}/license.rst" +] +with open("links.rst") as f: + PROLOG_PARTS.extend(f.readlines()) - .. _Chipmunk2D: https://chipmunk-physics.net/ +rst_prolog = "\n".join(PROLOG_PARTS) - .. |pyglet Player| replace:: pyglet :py:class:`~pyglet.media.player.Player` - """.strip()) def strip_init_return_typehint(app, what, name, obj, options, signature, return_annotation): diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index 262061ccf..261556686 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -3,22 +3,103 @@ Contributing To Arcade ====================== -We would love to have you contribute to the project! There are several -ways that you can do so. +We would love to have you contribute to the project! -How to contribute without coding -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Arcade's powerful features and documentation couldn't +exist without help and contributions from users like you. -* **Community** - Post your projects, code, screen-shots, and discuss the Arcade library on the `Python Arcade SubReddit`_. -* Try coding your own animations and games. Write down notes on anything that - is difficult to implement or understand about the library. -* **Suggest improvements** - Post bugs and enhancement requests at the `Github Issue List`_. - -How to contribute code -^^^^^^^^^^^^^^^^^^^^^^ +Contributing Code +----------------- If you are interested in contributing code, please check out the `Github Contributing Guide`_ -.. _Python Arcade SubReddit: https://www.reddit.com/r/pythonarcade .. _Github Issue List: https://github.com/pythonarcade/arcade/issues .. _Github Contributing Guide: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md + +I Can't Code Yet +---------------- +Even as a complete beginner, there are several ways you can help. + +Tell Us About Documentation Issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Let us know if anything's off or hard to follow about this +documentation. + +It doesn't matter whether you've started :ref:`the platformer tutorial ` +or just happen to be looking around. Let us know if anything looks off. + +The best ways to report it are via `Discord `_ +or the `Arcade GitHub`_ repository, but we also have other +:ref:`community-locations`. + +To be clear, all of the following are worth reporting: + +* Accessibility issues such as poor contrast or readability +* Mistakes in spelling or grammar mistakes +* Poorly written or hard to read material +* Incorrect or outdated information +* Odd behavior in styles or UI +* Broken links + +Play Games made with Arcade +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Arcade users often participate in game jams. Helping them +is as easy as: + +#. Playing their games +#. Providing feedback via the game jam's comments + +That includes reporting bugs on their projects to help them improve. + +Create Art, Music, and Sound +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you're an artist or a musician, you can build your skills +through game jams or game asset communities. + +* `The Python Discord`_ hosts team formation and more for the `PyWeek`_ game jam +* `OpenGameArt.org `_ is a long-running game asset community +* Various pixel art communities exist on Discord and Reddit + +.. _contributing-bug-reports: + +Report Bugs +----------- + +If you see something weird, let the devs know! + +Whether it's via `GitHub `_ or the `Arcade Discord`_, +even a simple screenshot or video capture can help us make Arcade better. +This includes: + +* Crashes on launch or any other time +* Odd behavior in Arcade's examples +* Functions not working correctly + + +Excellent Bug Reports +^^^^^^^^^^^^^^^^^^^^^ +The best bug reports are specific and repeatable. + +The following steps helps us fix bugs faster by making it easier to find +the source of the problem. + +#. Note your :ref:`Python and Arcade versions ` +#. Try to figure out when and how to make the bug happen + + * Remember: this can be hard, and that's okay + * If you can't put it into words, any of the following can help! + + * Screenshots or video recordings + * Error traceback + * Example code that makes the problem happen + +#. Search the `GitHub Issue List`_ for anything similar + + * If it exists, comment + * If not, post a new one + +Don't worry too much about posting duplicates. We can always cross-reference +issues if it's a duplicate. If you're unsure, you can always ask on `Discord `_. + diff --git a/doc/get_started/arcade_book.rst b/doc/get_started/arcade_book.rst index 87130a0db..48ebb28d4 100644 --- a/doc/get_started/arcade_book.rst +++ b/doc/get_started/arcade_book.rst @@ -29,6 +29,8 @@ If you are already familiar with basic Python programming, follow the If you are just learning how to program, see the `Learn Arcade book `_. +.. _skill_tree: + Arcade Skill Tree ----------------- diff --git a/doc/get_started/install.rst b/doc/get_started/install.rst index f3eaf3da9..60e9f0b4a 100644 --- a/doc/get_started/install.rst +++ b/doc/get_started/install.rst @@ -1,11 +1,72 @@ -.. include:: /links.rst +.. .. include:: /links.rst .. _install: Install ======= +.. _install_requirements: + +Requirements +------------ +:mod:`pyglet` + +All systems require Python 3.9 or higher on a desktop or laptop device. + +:ref:`Web ` and :ref:`mobile ` are currently +unsupported. + +Windows, Linux, and Intel Mac +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Your computer can likely run Arcade if it supports Python 3.9 or higher. + +In general, even older convertible Windows tablets will work as long as they: + +#. have an Intel or AMD processor +#. were made in the last 10 years + +.. note:: ARM-based Windows or Linux tablets may have issues. + + These devices may or may not work. the :ref:`requirements_raspi` + +Windows +""""""" + +To avoid strange issues, install Python as follows: + +#. Download Python from the `official Windows download page `_ +#. While installing, look for a checkbox marked "Add Python to PATH" +#. When you see it, make sure it is checked before proceeding + +.. important:: Avoid the Microsoft Store version of Python. + + It has a history of hard-to-fix bugs which make + development more difficult than it needs to be. + +.. _requirements_mac_mseries: + +M-Series Macs +""""""""""""" +Apple first released Macs with M-series processors in 2020. They may have a few +issues with window focus and unsigned applications. If something odd happens, you +can always :ref:`ask for help. `. + +.. _requirements_raspi: + +Raspberry Pi and Other ARM SBCs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Arcade and :py:mod:`pyglet` teams have verified the Raspberry Pi 4 and 5 +as working. The Raspberry Pi 400 will also likely work, but other Pi models will not. + +To learn more, please see: + +* :ref:`faq-raspi` +* :ref:`sbc_supported_raspi` + + Using pip --------- @@ -65,8 +126,13 @@ For example:: python -m arcade.examples.sprite_explosion_bitmapped -Built-in resource + +Batteries Included ------------------ -Arcade comes with a set of built-in assets that can be used in simple project -while learning the library. See the :ref:`resources` section. +:ref:`resources` mean you're ready to start right away. Since all of Arcade's assets are +:ref:`permissive_almost_all_public` or similarly licensed, you're free to create games +however you like. + +* :ref:`The Built-In Resources ` page lets you preview Arcade's built-in assets +* :ref:`The Platformer Tutorial ` will help you get started right away diff --git a/doc/index.rst b/doc/index.rst index d36956388..1fd4d6284 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,16 +1,11 @@ :hide-toc: -.. image:: images/logo/arcade-logo.svg - :width: 10% - :class: right-image .. _main_page: The Python Arcade Library ========================= -.. |Go| image:: images/woman_sprinter.svg - .. container:: main-page-item-wrapper-header @@ -29,9 +24,11 @@ The Python Arcade Library -Arcade is an easy-to-learn Python library for creating 2D video games. It is -ideal for people learning to program, or developers that want to code a 2D -game without learning a complex framework. +Arcade is an easy-to-learn Python library for creating 2D games and more. The +friendly API caters to both beginners and experts alike. Do you want to make +something small, or explore the full power of shaders? It's up to you. + +What will you make? .. raw:: html @@ -42,32 +39,63 @@ game without learning a complex framework.

Quick Arcade Library Introduction Video

-The library was originally designed to be used in an educational setting, but -it has evolved to be a powerful library for creating games. It is used in -education, prototyping, and game jams. Hobbyists wanting to create a game -quickly can benefit from the library's simple API. +Documentation and Community +--------------------------- + +Arcade provides documentation for every experience level. +The :ref:`skill_tree` or :ref:`main-page-tutorials` are good +for getting started. You can explore the following to +learn more: -Documentation -------------- +* :ref:`faq` has fast answers to common questions +* :ref:`intro_learning_resources` covers the documentation types +* :ref:`how-to-get-help` if you're unsure where to start + +.. pending: #2433 https://github.com/pythonarcade/arcade/issues/2433 +.. raw:: html -Arcade provides several forms of documentation depending on the learning style of the user. -For beginners to programming the Arcade book is a great place to start. For those who prefer -to learn by examples the Arcade examples are a great resource. We also have various tutorials -for specific topics. More advanced users may prefer the API reference. +
-Open Source ------------ +More than Open Source +--------------------- + +Arcade makes sure licensing concerns stay out of your way: + +* Arcade's code uses the :ref:`permissive_mit` +* :ref:`The built-in resources ` don't require attribution +* Remixing :ref:`example code ` is encouraged + +.. pending: #2433 https://github.com/pythonarcade/arcade/issues/2433 +.. raw:: html -Arcade is free and open source. It is released under the MIT License. This means you can use it for free, -and you can even use it in commercial projects. Copying and adapting content from Arcade in educational -materials is highly encouraged. +
+This ensures you are free to create, including :ref:`commercial projects `. Get Involved ------------ -Arcade is developed by volunteers. +Let us know if you see a bug, a typo, or other room for improvement. + +The following :ref:`community-locations` are the best places +to reach the team or ask for help: + +* The `Arcade Discord`_ server +* The `Arcade GitHub`_ repo + +.. pending: #2433 https://github.com/pythonarcade/arcade/issues/2433 +.. raw:: html + +
+ +See :ref:`how-to-contribute` to learn how you can +help improve Arcade. + +.. pending: #2433 https://github.com/pythonarcade/arcade/issues/2433 +.. raw:: html + +
.. The main table of contents defining the sidebar navigation This content is not part of the main page itself. @@ -79,6 +107,8 @@ Arcade is developed by volunteers. about/intro about/faq + about/permissive_licensing + about/for_academia .. toctree:: :hidden: @@ -107,6 +137,7 @@ Arcade is developed by volunteers. programming_guide/texture_atlas programming_guide/resource_handlers programming_guide/opengl_notes + programming_guide/gles_raspi_and_sbc programming_guide/performance_tips programming_guide/headless diff --git a/doc/links.rst b/doc/links.rst index 8a8ed82e3..ba049fdd0 100644 --- a/doc/links.rst +++ b/doc/links.rst @@ -1,8 +1,40 @@ +.. pending: post-3.0 cleanup: +.. We try to include this thing in the rst_prolog in conf.py through ugly means +.. adding the lines doesn't help with the generated resources, nor am I in the mood +.. to clean it up right now. If it builds and looks nice, it ships. PDF comes later. +.. Do not include the following here: +.. 1. the pyglet doc (use :py:mod:`pyglet` / etc to auto-link the right version) +.. 2. links to files in the Arcade GitHub repo (use the conf.py + base URLs) (See https://github.com/pythonarcade/arcade/issues/2387) + +.. Dependencies +.. _Pymunk: https://www.pymunk.org/en/latest/index.html +.. _pyglet: https://pyglet.readthedocs.io/en/development/ +.. Transitive dependency (heart of Pymunk) +.. _Chipmunk2D: https://chipmunk-physics.net/ + +.. Arcade-specific links .. _Arcade book: https://learn.arcade.academy/ -.. _pyglet: https://pyglet.readthedocs.io/ .. _PyPI: https://pypi.org/project/arcade/ .. _Arcade GitHub: https://github.com/pythonarcade/arcade/ .. _Arcade Discord: https://discord.gg/ZjGDqMp .. _Twitter: https://x.com/ArcadeLibrary .. _Reddit: https://www.reddit.com/r/pythonarcade/ + +.. Arcade-related community engagement stuff +.. _PyWeek: https://pyweek.org/ +.. _The Python Discord: https://www.pythondiscord.com/ +.. _Kenney_nl: https://kenney.nl/ + +.. Concepts +.. _CC0: https://creativecommons.org/publicdomain/#publicdomain-cc0-10 +.. _Creative Commons licenses: https://creativecommons.org/share-your-work/cclicenses/ + +.. Licensing +.. _BibTeX: https://www.bibtex.org/Format/ + +.. Hardware / Software +.. _rpi_4: https://www.raspberrypi.com/products/raspberry-pi-4-model-b/ +.. _rpi_400: https://www.raspberrypi.com/products/raspberry-pi-400/ +.. _rpi_5: https://www.raspberrypi.com/products/raspberry-pi-5/ +.. _Raspberry Pi OS: https://www.raspberrypi.com/software/ diff --git a/doc/programming_guide/gles_raspi_and_sbc.rst b/doc/programming_guide/gles_raspi_and_sbc.rst new file mode 100644 index 000000000..a10a01559 --- /dev/null +++ b/doc/programming_guide/gles_raspi_and_sbc.rst @@ -0,0 +1,189 @@ +.. _opengl_es_requirements: + +OpenGL ES Devices: Raspberry Pi, Etc +==================================== + +Arcade normally requires OpenGL to render, but it also supports devices +with the right versions of OpenGL ES. If you're familiar with the topic, +you may want to skip to :ref:`requirements_gles` below. + +OpenGL ES +--------- + +`OpenGL ES `_ ("embeddedable subset") is a special +variant of OpenGL tailored for mobile and embedded devices. + +Like the standard OpenGL API, it has both feature versions +and optional extensions. + +.. _gles_def: https://www.khronos.org/opengl/wiki/OpenGL_ES + + +.. _sbc_supported_raspi: + +Supported Raspberry Pi Configurations +------------------------------------- + +As of October 2024, the Arcade and `pyglet`_ teams verified the following to +work: + +* `Raspberry Pi 4 `_ running `Raspberry Pi OS`_ +* `Raspberry Pi 5 `_ running `Raspberry Pi OS`_ + +Although the `Raspberry Pi 400 `_ has never been tested, it +*may* work. It uses Raspberry Pi 4 hardware inside a keyboard form factor. + +Operating Systems +^^^^^^^^^^^^^^^^^ + +Although we test with `Raspberry Pi OS`_, other operating systems may work. + +Raspberry Pi Linux Distros +"""""""""""""""""""""""""" +Since Raspberry Pi OS is a Linux distribution, similar distros are likely to +work. These include: + +* `Debian's Raspberry Pi images `_ +* `Fedora's Raspberry Pi images `_ + +Windows for Raspberry Pi +"""""""""""""""""""""""" +There are no known attempts to run Arcade on Windows for +Raspberry Pi or any other ARM device. In theory, it's +possible. However, the following considerations apply: + +* Windows is said to be sluggish on Raspberry Pi devices +* :ref:`Arcade's binary dependencies ` might not have builds for Windows on ARM +* Be sure to install Python from the official download page +* Avoid the Microsoft app store version of Python + +.. _sbc_unsupported_raspis: + +Unsupported Raspberry Pi Devices +-------------------------------- + +Some Raspberry Pi devices cannot run Arcade because +they do not support the :ref:`required OpenGL ES features `. + +Incompatible Older Devices +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The original Raspberry Pi is unsupported +* The Raspberry Pi 2 is unsupported +* The Raspberry Pi 3 is unsupported + +Incompatible New Devices +^^^^^^^^^^^^^^^^^^^^^^^^ +Some newer devices also lack support for the required features. +Each is either a microcontroller or a reduced-power variant of +older Pi hardware. + +The table below lists these newer incompatible Raspberry Pi devices. + +.. list-table:: Recent Incompatible Raspberry Pi Devices + :header-rows: 1 + + * - Device + - Type + + * - `Pi Pico`_ (and W version) / `RP2040 `_ + - Microcontroller + + * - `Pi Pico 2`_ (and W version) / `RP2350`_ + - Microcontroller + + * - `Pi Zero`_ (plus W version) + - Mini-SBC + + * - `Pi Zero 2`_ (plus W and WH versions) + - Mini-SBC (based on Pi 3 hardware) + +.. _RP2350: https://www.raspberrypi.com/products/rp2350/ +.. _Pi Zero: https://www.raspberrypi.com/products/raspberry-pi-zero/ +.. _Pi Zero 2: https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/ +.. _Pi Pico 2: https://www.raspberrypi.com/products/raspberry-pi-pico-2/ +.. _Pi Pico: https://www.raspberrypi.com/products/raspberry-pi-pico/ +.. _wiki_pi2040: https://en.wikipedia.org/wiki/RP2040#Boards + +.. _sbc_requirements: + +SBC Requirements +---------------- +Any Single Board Computer (SBC) which meets the following +requirements may work. If you are a parent or educator shopping for a +compatible SBC, please see the :ref:`sbc_rule_of_thumb`. + + +Standard Python +^^^^^^^^^^^^^^^ +Arcade 3.0.0 requires Python 3.9 or higher. + +In practice, this means running Linux. In theory, it may be possible to run Arcade +on an ARM-specific version of Windows, but nobody has tried this before. + +.. _requirements_gles: + +Supported OpenGL ES Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Both Arcade and `pyglet`_ can run via OpenGL ES on devices with either: + +* OpenGL ES 3.2 or higher +* OpenGL ES 3.1 with certain extensions + +To learn more, please see the `pyglet manual page on OpenGL ES `_. + +.. pending: post-3.0 cleanup # Faster and more reliable than getting the external ref syntax to work +.. _pyglet-opengles: https://pyglet.readthedocs.io/en/development/programming_guide/opengles.html + + +If you are unsure, you may be able to try to install Arcade, then +test both Arcade and pyglet. If an SBC board is properly designed, +incompatibility will result in an error without damaging the hardware. + + +.. _sbc_binary_deps: + +Arcade's Binary Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Arcade 3.0.0 depends on the following binary packages from PyPI: + +#. :py:mod:`pymunk` +#. :py:mod:`pillow ` + +If one of these packages hasn't been compiled for your SBC's +CPU architecture, you will not be able to install Arcade. In general, +SBCs compatible with amd64 or the most common ARM instruction sets +should work. + +.. _requirements_sbc_psu: + +An Adequate Power Supply +^^^^^^^^^^^^^^^^^^^^^^^^ + +SBCs require an adequate power supply to function correctly. + +If you experience an issue with a crash or strange error while usin +Arcade on a Raspberry Pi or any other device, please try the following: + +#. Make sure you are using a quality power supply from a reputable vendor +#. Unplug any non-essential external hardware such: + + * external drives + * cameras + * USB devices + +#. Try to replicate the problem again + +If the crash or problem suddenly vanishes, you may be experiencing +a brownout. This occurs when the hardware experiences insufficient +power due to an inadequate or faulty power supply. + +Fixing Brownout +""""""""""""""" + +You can try the following: + +* Use a powered USB hub between external devices and the SBC +* Replace the power supply with a high-quality one from a reputable vendor diff --git a/util/create_resources_listing.py b/util/create_resources_listing.py index 639a55696..01c71e8ef 100644 --- a/util/create_resources_listing.py +++ b/util/create_resources_listing.py @@ -3,12 +3,17 @@ Generate quick API indexes in Restructured Text Format for Sphinx documentation. """ +# fmt: off +# ruff: noqa +from __future__ import annotations + import math +import re import sys from collections import defaultdict -from functools import lru_cache +from functools import lru_cache, cache from pathlib import Path -from typing import List +from typing import List, Callable, Protocol import logging log = logging.getLogger(__name__) @@ -25,6 +30,7 @@ def announce_templating(var_name): _v = globals()[var_name] log.warning(f"Templated {var_name} as {_v!r}") + # The following are provided via runpy.run_path's init_globals keyword # in conf.py. Uncomment for easy debugger run without IDE config. try: @@ -36,7 +42,7 @@ def announce_templating(var_name): _URL_BASE = "https://github.com/pythonarcade/arcade" _ = FMT_URL_REF_PAGE # noqa except Exception as _: - FMT_URL_REF_PAGE = f"{_URL_BASE}/blob/{GIT_REF}/{{}}" + FMT_URL_REF_PAGE = f"{_URL_BASE}/blob/{GIT_REF}/{{}}" announce_templating("FMT_URL_REF_PAGE") try: _ = FMT_URL_REF_EMBED # noqa @@ -60,10 +66,10 @@ def announce_templating(var_name): ".url", ".txt", ".tiled-project", - ".ttf", ".pyc", ] + def skipped_file(file_path: Path): """Return True if file should be skipped.""" return file_path.suffix in skip_extensions @@ -89,6 +95,7 @@ def create_resource_path( path: Path, prefix: str = "", suffix: str = "", + restrict_to_bases=('system', 'assets') ) -> str: """ Create a resource path. We will use the resources handle @@ -96,45 +103,179 @@ def create_resource_path( from the path. """ path = path.relative_to(RESOURCE_DIR) - if path.parts[0] == "system": - path = path.relative_to("system") - elif path.parts[0] == "assets": - path = path.relative_to("assets") + base = path.parts[0] + if not restrict_to_bases or base in restrict_to_bases: + path = path.relative_to(base) else: - raise ValueError(f"Unexpected path: {path}") + raise ValueError(f"Unexpected path: {path}. Expected one of: {', '.join(repr(b) for b in expect_bases)}") return f"{prefix}:resources:{path.as_posix()}{suffix}" +# pending: post-3.0 cleanup # unstructured kludge +REPLACE_TITLE_WORDS = { + "ttf": "Kenney TTFs", + "gui": "GUI", + "window": "Window & Panel", + ".": "Top-level Resources" +} +# pending: post-3.0 cleanup # more unstructured filth +SKIP_TITLES = { + "Kenney TTFs" +} + + +@cache +def format_title_part(raw: str): + out = [] + for word in raw.split('_'): + if word in REPLACE_TITLE_WORDS: + out.append(REPLACE_TITLE_WORDS[word]) + else: + out.append(word.capitalize()) + + return ' '.join(out) + + +# starts at = for top of page, drill down for here +# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections +headings_lookup = ( + '=', # Page root heading + '-', + '^', + '"', +) + + +visited_headings = set() + + +def do_heading(out, relative_heading_level: int, heading_text: str) -> None: + """Writes a heading to the output file. + + If the page heading is beyond what we have symbols for, the Sphinx + ``.. rubric::`` directive will be used instead. + + Args: + out: A file-like object which acts like its opened with ``"w"`` + relative_heading_level: Heading level relative to the page root. + heading_text: The heading text to display. + + """ + out.write("\n") + print(f"doing heading: {heading_text!r} {relative_heading_level}") + num_headings = len(headings_lookup) + + if relative_heading_level >= num_headings: + # pending: post-3.0 cleanup + log.warning( + f"Using .. rubric:: due to running out of heading levels:" + f"({relative_heading_level} >= {num_headings})") + out.write(f".. rubric:: {heading_text}\n") + else: + header_char = headings_lookup[relative_heading_level] + out.write(f"{heading_text}\n") + out.write(f"{header_char * (len(heading_text))}\n") + out.write("\n") + + +PRIVATE_NAME = re.compile(r'^__') + + +def is_nonprotected_dir(p: Path): + return p.is_dir() and not PRIVATE_NAME.match(p.stem) + + +def is_unskipped_file(p: Path): + return not (p.is_dir() or p.suffix in skip_extensions) + + +class SupportsLT(Protocol): + def __lt__(self, other): ... + + +def filter_dir( + dir: Path, + keep: Callable[[Path], bool] = lambda path: True, + key: Callable[[Path], SupportsLT] | Callable | None = str, + reverse: bool = False, +) -> list[Path]: + """Iterate cleanly over directory elements as + + .. warning:: Don't give this or anything in this file circular symlinks. + + Args: + dir: the directory + keep: When to keep an item in the directory + key: how to sort the folder elements + reverse: whether to reverse the sort + Returns: + A list of paths matching keep and sorted by both key and reverse. + """ + kept = [p for p in dir.iterdir() if keep(p)] + if key or reverse: + kept.sort(key=key, reverse=reverse) + return kept + + def process_resource_directory(out, dir: Path): """ Go through resources in a directory. """ - for path in dir.iterdir(): - if not path.is_dir() or path.name.endswith("__"): - continue + + for path in filter_dir(dir, keep=is_nonprotected_dir): # out.write(f"\n{cur_node.name}\n") # out.write("-" * len(cur_node.name) + "\n\n") - file_list = [item for item in path.iterdir() if not (item.is_dir() or skipped_file(item))] + file_list = filter_dir(path, keep=is_unskipped_file) num_files = len(file_list) + if num_files > 0: # header_title = f":resources:{path.relative_to(RESOURCE_DIR).as_posix()}/" - raw_header = create_resource_path(path, suffix="/") - header_title = raw_header[:-2] if raw_header.endswith("./") else raw_header + raw_resource_handle = create_resource_path(path, suffix="/") + resource_handle = raw_resource_handle[:-2] if raw_resource_handle.endswith("./") else raw_resource_handle + + # pending: post-3.0 time to refactor all of this + parts = raw_resource_handle.replace(":resources:", "").rstrip("/").split("/") + display_parts = [format_title_part(part) for part in parts] + + for heading_level, part in enumerate(display_parts, start=1): + if part in SKIP_TITLES: + continue + as_tup = tuple(display_parts[:heading_level]) + if as_tup not in visited_headings: + do_heading(out, heading_level, part) + visited_headings.add(as_tup) + + if raw_resource_handle == ":resources:images/": + for f in file_list: + print(f.name) - if raw_header == ":resources:images/": + if raw_resource_handle == ":resources:fonts/ttf/": for f in file_list: print(f.name) + # pending: post-3.0 cleanup + out.write("\n") + out.write(".. figure:: images/fonts_blue.png\n") + out.write(" :alt: The bundled Kenney.nl fonts.\n") + out.write("\n") + out.write(" Arcade includes the following fonts from `Kenney.nl's font pack `_\n") + out.write(" are available using the path and filenames below.\n") + + n_cols = get_header_num_cols(raw_resource_handle, num_files) + widths = get_column_widths_for_n(n_cols) + # out.write(f"\n{header_title}\n") # out.write("-" * (len(header_title)) + "\n\n") - n_cols = get_header_num_cols(raw_header, num_files) - widths = get_column_widths_for_n(n_cols) - out.write(f"\n") - out.write(f".. list-table:: \"{header_title}\"\n") + out.write(f".. raw:: html\n\n") + out.write(f" {resource_handle}\n") + + # pending: post-3.0 cleanup? + #out.write(f".. list-table:: \"{header_title}\"\n") + out.write(f".. list-table::\n") out.write(f" :widths: {widths}\n") out.write(f" :header-rows: 0\n") out.write(f" :class: resource-table\n\n") @@ -198,7 +339,7 @@ def process_resource_files(out, file_list: List[Path]): file_path = FMT_URL_REF_PAGE.format(resource_path) out.write(f" {start_row} - `{path} <{file_path}>`_\n") # Link Tiled maps - elif suffix == ".json": + elif suffix in (".json", ".ttf"): file_path = FMT_URL_REF_PAGE.format(resource_path) out.write(f" {start_row} - `{name} <{file_path}>`_\n") else: @@ -217,19 +358,29 @@ def resources(): out = vfs.open(OUT_FILE, "w") out.write(".. _resources:\n") + + do_heading(out, 0, "Built-In Resources") + out.write("\n") - out.write("Built-In Resources\n") - out.write("==================\n") - out.write("\n") - out.write("Resource files are images and sounds built into Arcade that " - "can be used to quickly build and test simple code without having " - "to worry about copying files into the project.\n\n") - out.write("Any file loaded that starts with ``:resources:`` will attempt " - "to load that file from the library resources instead of the " - "project directory.\n\n") - out.write("Many of the resources come from `Kenney.nl `_ ") - out.write("and are licensed under CC0 (Creative Commons Zero). Be sure to ") - out.write("check out his web page for a much wider selection of assets.") + out.write("Every file below is included when you :ref:`install Arcade `. This includes the images,\n" + "sounds, fonts, and other files to help you get started quickly. You can still download them\n" + "separately, but Arcade's resource handle system will usually be easier.\n") + do_heading(out, 1, "Do I have to credit anyone?") + # Injecting the links.rst doesn't seem to be working? + out.write("That's a good question and one you should always ask when searching for assets online.\n" + "To help users get started quickly, the Arcade team makes sure to only bundle assets which\n" + # pending: post-3.0 cleanup # Why does it refuse to accept external links definitions? Who knows? + "are specifically released under `CC0 `_" + " or similar terms.\n") + out.write("Most are from `Kenney.nl `_.\n") # pending: post-3.0 cleanup. + + do_heading(out, 1, "How do I use these?") + out.write( + "Arcade projects can use any file on this page by passing a **resource handle** prefix.\n" + "These are strings which start with ``\":resources:\"``. To learn more, please see the following:\n\n" + "* :ref:`Sprite Examples ` for example code\n" + "* :ref:`The Platformer Tutorial ` for step-by-step guidance\n" + "* The :ref:`resource_handles` page of the manual covers them in more depth\n") out.write("\n") process_resource_directory(out, RESOURCE_DIR)