Merge branch 'master' into immutable-vectors

.cirrus.yml

@@ -1,31 +1,35 @@
-dockerfiles_task:
-  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
-  container:
-    image: ellerbrock/alpine-bash-git
-
-  script:
-    - ./.ci/dockerfiles/generate.sh
-    - git diff --exit-code
-
-
 docs_task:
   skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   container:
-    dockerfile: .ci/dockerfiles/docs
+    image: python:3.7-slim
+
+  install_script:
+    - apt update || true ; apt install -qq -y make
+    - pip install --upgrade-strategy eager -U -r requirements-docs.txt
+    - pip install .
 
-  install_script: pip install -e .
-  script: make -C docs/ html
+  script:
+    - make -C docs/ html
 
 
 Linux_task:
   skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   allow_failures: $CIRRUS_TASK_NAME =~ '.*-rc-.*'
   container:
     matrix:
-      - dockerfile: .ci/dockerfiles/python_3.6-slim
-      - dockerfile: .ci/dockerfiles/python_3.7-slim
-      - dockerfile: .ci/dockerfiles/python_3.8-rc-slim
-      - dockerfile: .ci/dockerfiles/pypy_3.6-slim
+      - image: python:3.6-slim
+      - image: python:3.7-slim
+      - image: python:3.8-rc-slim
+      - image: pypy:3.6-slim
+
+  install_script:
+    - >-
+      if command -v pypy3 >/dev/null || python3 -c 'import sys; exit(sys.implementation.version.releaselevel == "final")'; then
+        apt update || true;
+        apt install -qq -y pkgconf libsdl-image1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev libsdl1.2-dev libsmpeg-dev libportmidi-dev libswscale-dev libavformat-dev libavcodec-dev libfreetype6-dev gcc
+      fi
+    - pip install --upgrade-strategy eager -U -r requirements-tests.txt
+    - pip install .
 
   script:
     - command -v pypy3 >/dev/null && export PY=pypy3
@@ -51,7 +55,7 @@ macOS_task:
     - pyenv global ${PYTHON}
     - pyenv rehash
     - pip install --upgrade-strategy eager -U -r requirements-tests.txt
-    - pip install -e .
+    - pip install .
 
   script:
     - python3 --version
@@ -64,8 +68,12 @@ Windows_task:
   windows_container:
     os_version: 2019
     matrix:
-      - dockerfile: .ci/dockerfiles/python_3.6-windowsservercore-1809
-      - dockerfile: .ci/dockerfiles/python_3.7-windowsservercore-1809
+      - image: python:3.6-windowsservercore-1809
+      - image: python:3.7-windowsservercore-1809
+
+  install_script:
+    - C:\Python\python.exe -m pip install --upgrade-strategy eager -U -r requirements-tests.txt
+    - C:\Python\python.exe -m pip install .
 
   script:
     - C:\Python\python.exe --version

bors.toml

@@ -1,10 +1,9 @@
 status = [
-  "dockerfiles",
   "docs",
-  "Linux Dockerfile:.ci/dockerfiles/python_3.6-slim",
-  "Linux Dockerfile:.ci/dockerfiles/python_3.7-slim",
-  "Windows Dockerfile:.ci/dockerfiles/python_3.6-windowsservercore-1809",
-  "Windows Dockerfile:.ci/dockerfiles/python_3.7-windowsservercore-1809",
+  "Linux container:python:3.6-slim",
+  "Linux container:python:3.7-slim",
+  "Windows container:python:3.6-windowsservercore-1809",
+  "Windows container:python:3.7-windowsservercore-1809",
   "macOS PYTHON:3.6.8",
   "macOS PYTHON:3.7.2",
 ]

docs/clocks.rst

@@ -0,0 +1,35 @@
+Clocks
+======
+
+PPB has several ways to mark time: fixed-rate updates, frames, and idle time.
+These are all exposed via the event system.
+
+
+Updates
+~~~~~~~
+
+The :py:class:`ppb.events.Update` event is fired at a regular, fixed rate
+(defaulting to 60 times a second). This is well-suited for simulation updates,
+such as motion, running NPC AIs, physics, etc.
+
+
+Frames
+~~~~~~
+The :py:class:`ppb.events.PreRender` and :py:class:`ppb.events.Render` are fired
+every frame. This is best used for particle systems, animations, and anything
+that needs to update every rendered frame (even if the framerate varies).
+
+.. note::
+
+   While both :py:class:`PreRender <ppb.events.PreRender>` and
+   :py:class:`Render <ppb.events.Render>` are fired every frame, it is
+   encouraged that games only use :py:class:`PreRender <ppb.events.PreRender>`
+   to ensure proper sequencing. That is, it is not guaranteed when
+   :py:meth:`on_render` methods are called with respect to the actual rendering.
+
+
+Idle
+~~~~
+:py:class:`ppb.events.Idle` is fired whenever the core event loop has no more
+events. While this is primarily used by systems for various polling things, it
+may be useful for games which have low-priority calculations to perform.

docs/events.rst

@@ -25,6 +25,9 @@ These are core events from hardware and the engine itself.
 .. autoclass:: ppb.events.PreRender
    :members:
 
+.. autoclass:: ppb.events.Idle
+   :members:
+
 .. autoclass:: ppb.events.Render
    :members: