Merge pull request #178 from arnauddupuis/arnauddupuis/issue138

Add a console particle system (issue138)
pygamelib · Mar 14, 2022 · 95552db · 95552db
2 parents db01ac2 + 9d38feb
commit 95552db
Show file tree

Hide file tree

Showing 30 changed files with 3,817 additions and 133 deletions.
diff --git a/docs/source/circle_emitter_example.gif b/docs/source/circle_emitter_example.gif
diff --git a/docs/source/gfx_particles.rst b/docs/source/gfx_particles.rst
@@ -3,8 +3,49 @@
 particles
 =========
 
+.. versionadded:: 1.3.0
+
+Starting with version 1.3.0, the pygamelib now provides a particle system. It is for now
+a first limited version and it has a number of limitations.
+
+First, the particles are "non interactive" objects. They are not affected by board items
+or anything drawn on screen nor can they affect them. All particles are drawn on top of
+an already rendered screen.
+
+This means no fancy particle physics out of the box. It doesn't means that it is not
+doable. It just means that it is not existing out of the box.
+
+Second, although I did my best to make the particle system as efficient as possible,
+drawing a lot of moving elements in the terminal is very slow. So be mindful of
+the performances when using it.
+
+Now despite the limitations, the particle system still allow to do some very cool stuff.
+Here is a video example:
+
+.. raw:: html
+
+    <iframe width="560" height="315" src="https://www.youtube.com/embed/KnBOzVpapNY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+This is the benchmark of the particle system, the code is available on 
+`Ghithub <https://github.com/arnauddupuis/pygamelib/tree/master/examples/benchmark-particle-system>`_.
+
+.. important:: Like the UI module, the particles system works exclusively with the
+   screen buffer system (place, delete, render, update, etc.).
+   It doesn't work with Screen functions tagged "direct display" like display_at().
+
+.. toctree::
+
+   pygamelib.gfx.particles.CircleEmitter.rst
+   pygamelib.gfx.particles.ColorParticle.rst
+   pygamelib.gfx.particles.ColorPartitionParticle.rst
+   pygamelib.gfx.particles.EmitterProperties.rst
+   pygamelib.gfx.particles.ParticleEmitter.rst
+   pygamelib.gfx.particles.ParticlePool.rst
+   pygamelib.gfx.particles.Particle.rst
+   pygamelib.gfx.particles.ParticleSprixel.rst
+   pygamelib.gfx.particles.PartitionParticle.rst
+   pygamelib.gfx.particles.RandomColorParticle.rst
+   pygamelib.gfx.particles.RandomColorPartitionParticle.rst
+
 .. automodule:: pygamelib.gfx.particles
-    :members:
-    :inherited-members:
-    :undoc-members:
-    :show-inheritance:
+    :noindex:
diff --git a/docs/source/pygamelib.gfx.particles.CircleEmitter.rst b/docs/source/pygamelib.gfx.particles.CircleEmitter.rst
@@ -0,0 +1,49 @@
+CircleEmitter
+=============
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: CircleEmitter
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~CircleEmitter.__init__
+      ~CircleEmitter.apply_force
+      ~CircleEmitter.attach
+      ~CircleEmitter.be_notified
+      ~CircleEmitter.detach
+      ~CircleEmitter.emit
+      ~CircleEmitter.finished
+      ~CircleEmitter.notify
+      ~CircleEmitter.render_to_buffer
+      ~CircleEmitter.resize_pool
+      ~CircleEmitter.store_screen_position
+      ~CircleEmitter.toggle_active
+      ~CircleEmitter.update
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~CircleEmitter.active
+      ~CircleEmitter.column
+      ~CircleEmitter.particle_pool
+      ~CircleEmitter.row
+      ~CircleEmitter.x
+      ~CircleEmitter.y
+
+
diff --git a/docs/source/pygamelib.gfx.particles.ColorParticle.rst b/docs/source/pygamelib.gfx.particles.ColorParticle.rst
@@ -0,0 +1,47 @@
+ColorParticle
+=============
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: ColorParticle
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ColorParticle.__init__
+      ~ColorParticle.apply_force
+      ~ColorParticle.attach
+      ~ColorParticle.be_notified
+      ~ColorParticle.detach
+      ~ColorParticle.finished
+      ~ColorParticle.notify
+      ~ColorParticle.render
+      ~ColorParticle.reset
+      ~ColorParticle.reset_lifespan
+      ~ColorParticle.store_screen_position
+      ~ColorParticle.terminate
+      ~ColorParticle.update
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ColorParticle.column
+      ~ColorParticle.row
+      ~ColorParticle.x
+      ~ColorParticle.y
+
+
diff --git a/docs/source/pygamelib.gfx.particles.ColorPartitionParticle.rst b/docs/source/pygamelib.gfx.particles.ColorPartitionParticle.rst
@@ -0,0 +1,47 @@
+ColorPartitionParticle
+======================
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: ColorPartitionParticle
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ColorPartitionParticle.__init__
+      ~ColorPartitionParticle.apply_force
+      ~ColorPartitionParticle.attach
+      ~ColorPartitionParticle.be_notified
+      ~ColorPartitionParticle.detach
+      ~ColorPartitionParticle.finished
+      ~ColorPartitionParticle.notify
+      ~ColorPartitionParticle.render
+      ~ColorPartitionParticle.reset
+      ~ColorPartitionParticle.reset_lifespan
+      ~ColorPartitionParticle.store_screen_position
+      ~ColorPartitionParticle.terminate
+      ~ColorPartitionParticle.update
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ColorPartitionParticle.column
+      ~ColorPartitionParticle.row
+      ~ColorPartitionParticle.x
+      ~ColorPartitionParticle.y
+
+
diff --git a/docs/source/pygamelib.gfx.particles.EmitterProperties.rst b/docs/source/pygamelib.gfx.particles.EmitterProperties.rst
@@ -0,0 +1,26 @@
+EmitterProperties
+=================
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: EmitterProperties
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~EmitterProperties.__init__
+
+
+
+
+
+
diff --git a/docs/source/pygamelib.gfx.particles.Particle.rst b/docs/source/pygamelib.gfx.particles.Particle.rst
@@ -0,0 +1,47 @@
+Particle
+========
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: Particle
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Particle.__init__
+      ~Particle.apply_force
+      ~Particle.attach
+      ~Particle.be_notified
+      ~Particle.detach
+      ~Particle.finished
+      ~Particle.notify
+      ~Particle.render
+      ~Particle.reset
+      ~Particle.reset_lifespan
+      ~Particle.store_screen_position
+      ~Particle.terminate
+      ~Particle.update
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~Particle.column
+      ~Particle.row
+      ~Particle.x
+      ~Particle.y
+
+
diff --git a/docs/source/pygamelib.gfx.particles.ParticleEmitter.rst b/docs/source/pygamelib.gfx.particles.ParticleEmitter.rst
@@ -0,0 +1,49 @@
+ParticleEmitter
+===============
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: ParticleEmitter
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ParticleEmitter.__init__
+      ~ParticleEmitter.apply_force
+      ~ParticleEmitter.attach
+      ~ParticleEmitter.be_notified
+      ~ParticleEmitter.detach
+      ~ParticleEmitter.emit
+      ~ParticleEmitter.finished
+      ~ParticleEmitter.notify
+      ~ParticleEmitter.render_to_buffer
+      ~ParticleEmitter.resize_pool
+      ~ParticleEmitter.store_screen_position
+      ~ParticleEmitter.toggle_active
+      ~ParticleEmitter.update
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ParticleEmitter.active
+      ~ParticleEmitter.column
+      ~ParticleEmitter.particle_pool
+      ~ParticleEmitter.row
+      ~ParticleEmitter.x
+      ~ParticleEmitter.y
+
+
diff --git a/docs/source/pygamelib.gfx.particles.ParticlePool.rst b/docs/source/pygamelib.gfx.particles.ParticlePool.rst
@@ -0,0 +1,35 @@
+ParticlePool
+============
+
+.. currentmodule:: pygamelib.gfx.particles
+
+.. autoclass:: ParticlePool
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ParticlePool.__init__
+      ~ParticlePool.count_active_particles
+      ~ParticlePool.get_particles
+      ~ParticlePool.resize
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ParticlePool.pool
+
+