From 41ea4059d33b77a5bfd958901626f86f3c374b26 Mon Sep 17 00:00:00 2001 From: Piper Thunstrom Date: Sun, 30 May 2021 13:16:11 -0700 Subject: [PATCH 1/2] Initial outline of architecture reference documentation --- docs/architecture.rst | 154 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/architecture.rst diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 00000000..8d5d3e3a --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,154 @@ +How ppb Fits Together +=========================================================== + +This document is an overall reference of what ppb is, how it's organized, and +how to use the various pieces. + +The Conceptual Necessities +----------------------------------------------------------- +.. _arch-the-basics: + +1. A basic outline of the core elements of using ppb: + 1. The GameEngine + 2. Scenes + 3. Sprites + 4. Events, EventTypes, Event Handlers + 5. Flags? + 6. Assets? + +This section should be light and to the point: It's basically a technical +reference version of getting started and link to more detailed descriptions +further in this document. + +Things not included in this list but will be important to document: + +1. Systems and Systemslib +2. GameObject +3. Time? +4. Camera + +Events +----------------------------------------------------------- +.. _arch-events: + +1. What is an event +2. Event classes + 1. dataclasses/attr classes +3. Event dispatch + 1. The queue + 2. Conversion from EventName to on_event_name + 3. publication +4. Event handlers + 1. Naming rules + 2. Parameters + 3. accessible data + +The Game Engine +----------------------------------------------------------- +.. _arch-game-engine: + +1. Context managers +2. The children types (scenes, systems) +3. Event publication? +4. The run function +5. Events the Engine responds to +6. Idle event! + +Systems +----------------------------------------------------------- + +.. _arch-systems: + +1. Behaviors specific to the engine/across scenes +2. Context managers + 1. Why context managers + 2. Examples +3. Children (GameObjects) +4. Events! + +Scenes +----------------------------------------------------------- + +.. _arch-scenes: + +1. Conceptualization: a container that allows separating parts of games +2. Holds GameObjects + 1. Adding and removing game objects + 2. Querying Game Objects + 3. The Camera +3. The Scene lifecycle with examples +4. events + +Sprites +----------------------------------------------------------- + +.. _arch-sprites: + +1. What a Sprite is +2. How to build a sprite + 1. built in + 2. use basesprite to mixin in your own +3. Events + +Assets +----------------------------------------------------------- + +.. _arch-assets: + +1. An asset hooks into the built in asset loader + 1. Asynchrounous! + 2. Allows you to do work in a background thread + 3. Good for things you don't want happening during the game loop proper. +2. Usage + 1. How to instantiate. + 2. Expectations +3. Building new assets + +Flags +----------------------------------------------------------- + +.. _arch-flags: + +What they are, why we want them, constraints for the oddity of implementation. + +Renderer +----------------------------------------------------------- + +.. _arch-renderer: + +Details about the metadata driven renderer. + +sprite.image +sprite.position +sprite.facing/rotation +sprite.tint +sprite.opacity +??? + +Camera +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _arch-camera: + +Details about the camera, when it's instantiated, how it works (notes about +the aspect ratio being more important that the requested width/height.) + +Timekeeping +----------------------------------------------------------- + +.. _arch-time: + +utils.get_time +wall time +game time + +Input +----------------------------------------------------------- + +.. _arch-input: + +Supported inputs +what the flags look like +reasoning for uncommon names (button.Primary, Secondary, Tertiary) +How to interact with them +Warnings From 6c98e416baa4e85937023d90dfd628586bd44a80 Mon Sep 17 00:00:00 2001 From: Piper Thunstrom Date: Tue, 1 Jun 2021 13:25:13 -0700 Subject: [PATCH 2/2] Adds partial draft of conceptual overview arch doc. --- docs/architecture.rst | 47 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/docs/architecture.rst b/docs/architecture.rst index 8d5d3e3a..cb147bd8 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -1,4 +1,4 @@ -How ppb Fits Together + How ppb Fits Together =========================================================== This document is an overall reference of what ppb is, how it's organized, and @@ -8,9 +8,46 @@ The Conceptual Necessities ----------------------------------------------------------- .. _arch-the-basics: -1. A basic outline of the core elements of using ppb: - 1. The GameEngine - 2. Scenes +Put some introduction here. + +It is conceptually useful to consider PursuedPyBear applications as a tree of +nodes. In :code:`ppb` parlance, we refer to nodes as +:py:class:`GameObjects `. A game object can have any +number of children and are allowed to organize their internal children however +the developer likes. Each :py:class:`~ppb.gomlib.GameObject` is capable of +responding to :ref:`events `, which is the primary messaging +utility in :code:`ppb`. Ultimately, though, a :py:class:`~ppb.gomlib.GameObject` +is of little use in a vacuum. As such, :code:`ppb` provides a number of semantic +:py:class:`GameObjects ` with focused roles. + +The expected root of the :py:class:`~ppb.gomlib.GameObject` tree is the +:py:class:`~ppb.GameEngine`. It is important that you use +:py:class:`~ppb.GameEngine`, either directly or indirectly, for this object +because all other assumptions in :code:`ppb` are built on how +:ref:`the engine interacts with its children `. + +The children of the :py:class:`~ppb.GameEngine` come in two flavors: +:py:class:`Scenes ` and :py:class:`Systems `. + +The :py:class:`Systems ` are how :code:`ppb` developers +add new features to the engine. They also allow you to add code that crosses +:py:class:`~ppb.Scene` boundaries, or interacts with external software or +systems. They are Python context managers to allow for setup and teardown of +external resources, and include their own children like any +:py:class:`~ppb.gomlib.GameObject`. + +.. todo:: + + Need a link to the Systems section. Might need to add language? + +:py:class:`Scenes ` allow you to break up your applications into +discreet parts. Most of the time, :py:class:`Scenes ` need little +more than an initialization function as they're ultimately there to hold +together the pieces that make up a section of a game, but like other +:py:class:`GameObjects ` they can respond to events. The +Scene's children are usually :py:class:`Sprites `. + +A basic outline of the core elements of using ppb: 3. Sprites 4. Events, EventTypes, Event Handlers 5. Flags? @@ -22,8 +59,6 @@ further in this document. Things not included in this list but will be important to document: -1. Systems and Systemslib -2. GameObject 3. Time? 4. Camera