lzrtag-base 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e1aba4b3577f72ee4c4aca45caca65e157cfa522
+  data.tar.gz: 9582f9f9a6c478c97de4c837ad6eadfb2c44c451
+SHA512:
+  metadata.gz: a2a6bcaeefeddece09a26ee91e9dd608aa5d8450dc4ff943b23d01ad995f07533cdcc278336b37e92873de1f9cc4ce468e66df5806225e01c8ce23acb18eb313
+  data.tar.gz: f5dea5415de79a54ab9c4d5bd7e81e774daae5498d4b6005c21a68c5d9ddba6f9ca7540b1159f78cffa786507d19d25f52a1d3153320e70c64234db833616f64

data/README.md

@@ -0,0 +1,98 @@
+
+# LZRTag base library gem
+
+This is the full documentation of the LZRTag ruby gem library.
+It includes examples for the different elements of this code, and even a basic
+deathmatch game to show off the mechanics more interactively.
+
+## Prerequisites
+Let's first start off by installing and setting up everything that's needed
+to run a LZRTag game. We'll assume you have at least one, preferrably as many as possible,
+LZRTag hardware sets with the latest firmware - consult the [HackADay page](bit.ly/XASLZR) as well as the [GitHub Wiki page](https://github.com/XasWorks/LZRTag/wiki/Assembly) on soldering them up.  
+We will also need a WiFi network and a MQTT Server, either local or hosted, like
+Flespi.io, with the LZRTag hardware set up to connect to the server. Successful
+connection is indicated by a smooth, very slow waver of the blue connection LED
+on the sets. If you want to double-check connection you can subscribe to the
+Lasertag/# topic on your MQTT server and check if the sets are pinging properly.
+
+Once we are sure that the sets are connected properly run `gem install lzrtag-base`.
+The latest ruby is recommended for performance reasons, however, this code should work
+with anything above 2.3.
+
+## Testing on IRB
+As a first experience, I'd recommend playing with the interface class on the interactive
+ruby console. It's a great way to see the immediate effects of various commands
+on the set, and is kinda fun, too.
+
+Let's first start up the console and require the library.
+```IRB
+irb(main):001:0> require 'lzrtag.rb'
+=> true
+irb(main):002:0>
+```
+This will load all necessary files, and will also provide a few helper functions
+to access the correct classes etc.  
+Next, let's establish an MQTT connection and start the handler.
+
+```IRB
+irb(main):002:0> mqtt = MQTT::SubHandler.new('localhost'); # Or your address
+MQTT: localhost trying reconnect...
+MQTT: localhost connected!
+irb(main):003:0> handler = LZRTag.Handler.new(mqtt);
+I LZR::Handler init finished
+```
+
+Awesome! The handler should now be connected to your server, and should have registered
+new players. If you look at your MQTT Server, for example with MQTT-Spy, you
+should see that any connected players will now have an ID.
+
+Let's see what players the system has already registered:
+
+```irb
+irb(main):004:0> handler.each do |player| puts player; end;
+#<Player:DEVICE_ID#OFFLINE, Team=0, Battery=4.19, Ping=218ms>
+```
+
+Players have a nice inspect function so they don't clutter the console too much when printed. Neat, huh?
+
+Alright, we need to fetch one single player to play with. If you have a device ID
+(their MAC, used on the MQTT network to identify them) you can use that, otherwise
+use the ShotID (number, 0..255). Let's do  that now - and while we're at it,
+let's identify the player:
+
+```irb
+irb(main):005:0> player = handler["BC.DD.C2.D0.63.F8"]
+=> #<Player:#OFFLINE, Team=0, Battery=4.19, Heap=0, Ping=218ms>
+irb(main):006:0> player.hit
+```
+
+You should have seen and heard one of the sets flashing up - that's the one we
+just retrieved. We can also colour it green and make it a little brighter!
+
+```irb
+irb(main):007:0> player.team = 2
+=> 2
+irb(main):08:0> player.brightness = :active
+=> :active
+```
+
+Alright, awesome - let's not go too deep into what you can do with the player.
+That's what the Ruby documentation is for, after all.
+
+## And now?
+Well, more complex behaviours can be added with so-called hooks. These are extensions
+that perform automated tasks based on different events in the game, and use the
+internal "event system".  
+There is a list of currently used events available, as well as documentation on
+the hooks class. You can make your own, or use the standard hooks provided in this
+library - it's up to you!
+
+Since a game is way more than just behaviours though, there are also "Games".
+Each game is a collection of hooks, which provide the behaviour of the game. However,
+they also include a description of different phases - stuff like "initializing",
+"playing", "selecting teams", etc.  
+The application can seamlessly switch between phases of a game, with each phase
+defining which hooks to enable or disable and what to do every game tick.
+
+It's best to look right into the documentation on those classes, since demonstrating
+them bit by bit isn't really possible.

data/docs/EventSymbols.md

@@ -0,0 +1,117 @@
+
+
+This file will document all known internal Lasertag events and their purpose.
+Users may add their own events via the standard system by simply sending a new event -
+however, only the following event symbols and payloads will be used by the provided software.
+
+
+## Game related events
+
+###### :gameTick
+Triggered in regular intervals, default 0.1s  
+Payload is [deltaTime since last tick].
+It is only triggered when a game is present.
+
+*Game class alternative:* Describe per-tick code using the
+"phase" DSL. It allows easy and clean specification of tick code.
+
+###### :gameStarting
+Triggered when a new game is selected, either in Ruby or via MQTT.  
+Payload is [newGame]
+
+###### :gamePhaseEnds
+Called immediately before the phase of a game is changed. Can be used to de-init some settings, or to finalize for example a player
+team selection.  
+The payload is [oldPhase, nextPhase]
+
+*Game class alternative:* Descibe per-tick code using the "phase_end" DSL.
+
+###### :gamePhaseStarts
+Called immediately after the game's phase was changed to a new phase. Can, and should, be used to prepare a game's setting.  
+The payload is [newPhase, oldPhase]
+
+*Game class alternative:* Descibe per-tick code using the "phase_prep" DSL.
+
+###### :playerEnteredGame
+Called whenever a player is added to the list of game players.  
+Payload is [thePlayer]
+
+###### :playerLeftGame
+Called whenever a player was removed from the list of game players.  
+Payload is [thePlayer]
+
+## Player config options
+The following options will be triggered whenever some config of the player changes, and are mainly useful to trigger events or
+keep track of the players etc.
+
+###### :playerRegistered
+Triggered when a brand new player is found on the MQTT network.
+This will effectively only happen at the start of the server, or when a new player is turned on.  
+Payload is [thePlayer]
+
+###### :playerConnected
+Triggered whenever a player reconnects to the server, either when restarting the server or mid-game after a disconnect.  
+Payload is [thePlayer]
+
+###### :playerDisconnected
+Triggered whenever a player looses connection to the MQTT server (detected via the LWT topic).  
+Payload is [thePlayer]
+
+## Hardware player signals
+These signals are sent in response to various player actions, as well as most of Hardware Player's
+configuration changes.
+
+###### :navSwitchPressed
+Triggered when the player presses a navigation switch.  
+Payload is [thePlayer, direction (0..2)]
+
+###### :poseChanged
+Triggered when the player changes the pose of the weapon. Possible poses are listed
+under the Lasertag Hardware Player's "gyroPose" attribute
+Payload is [thePlayer, poseSymbol]
+
+###### :playerTeamChanged
+Triggered when the team of a player is changed.  
+Payload is [thePlayer, newTeam (0..7), oldTeam (0..7)]
+
+###### :playerBrightnessChanged
+Triggered when the brightness of a player is changed. For a list of brightness
+symbols, see Hardware Player's "brightness" attribute.  
+Payload is [thePlayer, newBrightness, oldBrightness]
+
+###### :playerGunChanged
+Triggered when the gun number of the player is changed.  
+Payload is [thePlayer, newGun, oldGun]
+
+*TODO:* The gun number should be replaced by an ID string, when the
+gun configuration is moved to a Filesystem-based one (possibly by loading from JSON)
+
+## Player life signals
+These signals are sent whenever the player's HP count or life status is changed,
+and let the application handle things like scoring damage and kills, and triggering
+things like the heartbeat.
+
+###### :playerRegenerated
+Triggered whenever the player gains a bit of health, this can be by self-healing or
+by a medic or similar providing health.  
+Payload is [thePlayer, deltaLife, sourcePlayer | nil]
+
+###### :playerFullyRegenerated
+Triggered similarly to :playerRegenerated, but only whenever the player has fully
+regenerated and has reached maxLife again.  
+Payload is [thePlayer, sourcePlayer | nil]
+
+###### :playerHurt
+Triggered whenever a player is hurt after a hit arbitration
+and damage calculation, or by other game events.  
+Payload is [thePlayer, deltaLife]
+
+###### :playerRevived
+Triggered whenever a player was revivied, either by a timeout
+or by regenerating enough health, or by another person.  
+Payload is [thePlayer, sourcePlayer]
+
+###### :playerKilled
+Triggered whenever a player was killed, often by another player,
+but can be by system damage (killzones etc.)  
+Payload is [thePlayer, sourcePlayer | nil]

data/docs/MQTTBranches.md

@@ -0,0 +1,74 @@
+# MQTT Branch setup description
+
+## Weapon Branches
+The weapons are the main unit of the Lasertag system. As such, they use a specific
+branch setup to minimize traffic to them, while making code maintaining easier.
+
+The basic branch setup is:
+> Lasertag/Players/**ID**/**Keys...**
+
+- **ID** is the MAC of the Player, allowing unique identification of
+	each set out of the box.
+- **Key** is a one- or two-layer key of the attribute to change.
+	Attributes are grouped, making it easier to subscribe to one group of attributes
+	without having to worry about the others.
+
+In the following, the different groups of keys will be outlined, followed by
+a description of each attribute per group.
+
+### Non-Grouped attributes
+
+|Keys|Data|Descrition|Retained|
+|--|--|--|--|
+|Connection|String|LWT Topic of the sets. "OK" if connected.|Yes|
+
+### Config attributes
+
+Any attributes under this category can be found under "/CFG/**KEY**".
+They are slow-changing configuration parameters for the weapons.
+
+|Key|Data|Descrition|Retained|
+|--|--|--|--|
+|Team|STR Number|Team number, 0 to 7|Yes|
+|Brightness|STR Number|Brightness preset number. In Ruby, handled by symbols|Yes|
+|Name|String|User-set name of the weapon|Yes|
+|Dead|"1" or "0"|Sets the alive-ness of the gun.|Yes|
+|Dead/Timed|STR Number|Number, in seconds, to kill the weapon for. Auto-revives|No|
+|GunNo|STR Number|Gun preset number. 0 or "" disable shooting|Yes|
+|Marked|STR Number|Color to mark the set with. 1-7 use team colors, custom colors can be used|Yes|
+|Heartbeat|"1" or "0"|Enables/Disables heartbeat of the weapon|Yes|
+|Hit|STR Number|Number, in seconds, to make the gun show that it's hit|No|
+|Vibrate|STR Number|Number, in seconds, for which to make the gun vibrate|No|
+
+### Sound attributes
+
+Any attributes under this category are found under "/Sound/**KEY**"
+They all relate to noises the gun can make.
+
+|Key|Data|Descrition|Retained|
+|--|--|--|--|
+|Note|uint32_t[3]|Raw note play data. Frequency(Hz), Volume (0..2^16), Duration(ms)|No|
+|File|String|Name of a raw audio file to play.|No|
+
+### Hardware attributes
+
+Any attributes under this category are found under "/HW/**KEY**"
+They all relate to the hardware of the system, such as battery etc.
+
+|Key|Data|Descrition|Retained|
+|--|--|--|--|
+|Ping|uint32_t[3]|Battery, free-heap and ping data|No|
+|NSwitch|STR Number|Navigation switch press info (0-3)|No|
+|Gyro|String|Clear string of the pose the gyroscope is reporting|Yes|
+
+### Statistics Attributes
+
+Any attributes under this category are found under "/Stats/**KEY**"
+They all relate to various game statistics that do not directly influence the hardware, but are still relevant to the game and how it plays out.
+
+
+|Key|Data|Descrition|Retained|
+|--|--|--|--|
+|HP|STR Number|Float number, 0  to 100 (or more with shields)|Yes|
+|Ammo|uint32_t[2]|Current and Max ammo of the weapon|Yes|
+|Ammo/Set|STR Number|Give the player some ammo (*WIP*)|No|

data/lib/lzrtag.rb

@@ -0,0 +1,13 @@
+
+module LZRTag
+	def self.Handler()
+		return LZRTag::Handler::Game;
+	end
+end
+
+require_relative 'lzrtag/handler/game_handler.rb'
+require_relative 'lzrtag/hooks/standard_hooks.rb'
+
+require_relative 'lzrtag/game/base_game.rb'
+
+require_relative 'lzrtag/map/map_set.rb'

data/lib/lzrtag/game/base_game.rb

@@ -0,0 +1,220 @@
+
+require_relative '../hooks/base_hook.rb'
+
+# @author Xasin
+module LZRTag
+	module Game
+		# The base game class.
+		# It implements a DSL that allows users to easily
+		# define their own games, and hooks in with the
+		# game event system
+		# @example
+		#   class OwnGame < LZRTag::Game::Base
+		#      def initialize(handler)
+		#         super(handler);
+		#         @tickTime = 1;
+		#      end
+		#
+		#      hook :dmgHook, LZRTag::Hook::Damager
+		#
+		#      phase :running do |deltaTick|
+		#         puts "I tick!"
+		#      end
+		#
+		#      on :playerRegistered do |newPlayer|
+		#         puts "Hello new player!";
+		#      end
+		#   end
+		#
+		#   handler.start_game(OwnGame)
+		#   # Alternatively, register the game and let it be activated via MQTT
+		#   handler.register_game("My Game", OwnGame);
+		class Base < Hook::Base
+			# Returns a list of all currently instantiated hooks
+			attr_reader :hookList
+			# Returns the current per-tick target time. Can, and should, be set during
+			# constructor to control the granularity of the game
+			attr_reader :tickTime
+
+			# Returns a list of the known phases of this game
+			attr_reader :phases
+
+			# @private
+			# This function is meant for the DSL,
+			# to allow adding to the class itself
+			def self.get_phase_map()
+				@globalPhaseMap ||= Hash.new();
+				return @globalPhaseMap;
+			end
+			# @private
+			# @see get_phase_map()
+			def self.get_phase_prep_map()
+				@globalPhasePrepMap ||= Hash.new();
+				return @globalPhasePrepMap;
+			end
+			# @private
+			# @see get_phase_map()
+			def self.get_phase_end_map()
+				@globalPhaseEndMap ||= Hash.new();
+				return @globalPhaseEndMap;
+			end
+			# @private
+			# @see get_phase_map()
+			def self.get_hooks()
+				@globalHookList ||= Hash.new();
+				return @globalHookList;
+			end
+
+			# This function returns a list of possible phases
+			# and their tick callbacks
+			def get_phase_map()
+				return @phaseMap
+			end
+
+			# Initializes a generic game handler.
+			# This function is usually not called by the user,
+			# but instead by the LZRTag::Handler::Game when
+			# starting a game.
+			# @param handler [LZRTag::Handler::Base] any valid
+			# 		LZRTag handler that the game shall follow
+			#
+			def initialize(handler)
+				super(handler)
+
+				@hookList = Array.new();
+				self.class.get_hooks().each do |hookID, hookData|
+					@hookList << hookData[0].new(@handler, **hookData[1])
+				end
+
+				@tickTime = 0.1;
+
+				@phaseMap = self.class.get_phase_map();
+				@phasePrepMap = self.class.get_phase_prep_map();
+				@phaseEndMap = self.class.get_phase_end_map();
+
+				@phases = [@phaseMap.keys, @phasePrepMap.keys].flatten.uniq
+
+				@phaseTime = 0;
+				@phaseLastTime = 0;
+			end
+
+			# @!group DSL functions
+
+			# DSL function to add a Hook type to this game.
+			# Any hook type added by this function will be instantiated when the game
+			# itself is instantiated, and will be linked in with the internal game
+			# signals.
+			# @param hookID [Symbol] The ID of the hook, used for later referencing
+			# @param hookType [Hook::Base] The class of the hook to instantiate
+			# @param hookOptions [Hash] A hash of options to pass to the constructor of the hook
+			def self.hook(hookID, hookType, hookOptions = {})
+				raise ArgumentError, "Hook ID needs to be a symbol!" unless hookID.is_a? Symbol
+				unless hookType.is_a? Class and hookType < LZRTag::Hook::Base
+					raise ArgumentError, "Hook needs to be a LZR::Hook!"
+				end
+				raise ArgumentError, "Hook options need to be a hash" unless hookOptions.is_a? Hash
+				get_hooks()[hookID] << [hookType, hookOptions];
+			end
+
+			# DSL function to provide a phase tick code to this game
+			# The block provided to this function will be executed every game tick,
+			# with the delta-time since last tick as parameter.
+			# @param phaseName [Symbol] The name of the phase during which to execute this code
+			# @yield [deltaTime] Calls this block every game-tick during the specified phase
+			def self.phase(phaseName, &block)
+				raise ArgumentError, "Block needs to be given!" unless block_given?
+
+				phaseName = [phaseName].flatten
+				phaseName.each do |evt|
+					unless (evt.is_a? Symbol)
+						raise ArgumentError, "Phase needs to be a symbol or array of symbols!"
+					end
+					self.get_phase_map()[evt] = block;
+				end
+			end
+
+			# DSL function to provide a callback immediately after switching to a new phase.
+			# The provided block will be called only once, right after a phase switch happened.
+			# As such, it can be used to prepare game timer settings, player classes, etc.
+			# @param phaseName [Symbol] The name of the phase before which to execute
+			# @yield [oldPhase] Calls the block right after a switch, with the old phase as parameter
+			def self.phase_prep(phaseName, &block)
+				raise ArgumentError, "Block needs to be given!" unless block_given?
+
+				phaseName = [phaseName].flatten
+				phaseName.each do |evt|
+					unless (evt.is_a? Symbol)
+						raise ArgumentError, "Phase needs to be a symbol or array of symbols!"
+					end
+					self.get_phase_prep_map()[evt] ||= Array.new()
+					self.get_phase_prep_map()[evt] << block;
+				end
+			end
+
+			# DSL function to provide a callback immediately before switching to a new phase.
+			# The provided block is guaranteed to execute before any phase and phase_prep blocks,
+			# giving the user an option to reset and clean up after themselves.
+			# @param phaseName [Symbol] Name of the phase after which to call this block
+			# @yield [newPhase] Calls the block right before the switch, with the upcoming phase as parameter
+			def self.phase_end(phaseName, &block)
+				raise ArgumentError, "Block needs to be given!" unless block_given?
+
+				phaseName = [phaseName].flatten
+				phaseName.each do |evt|
+					unless (evt.is_a? Symbol)
+						raise ArgumentError, "Phase needs to be a symbol or array of symbols!"
+					end
+					self.get_phase_end_map()[evt] ||= Array.new()
+					self.get_phase_end_map()[evt] << block;
+				end
+			end
+
+			# @!endgroup
+
+			# @private
+			def consume_event(evt, data)
+				super(evt, data);
+
+				case evt
+				when :gameTick
+					handle_game_tick(*data);
+				when :gamePhaseStarts
+					handle_phase_change();
+				when :gamePhaseEnds
+					if @phaseEndMap[data[0]]
+						@phaseEndMap[data[0]].each do |cb|
+							instance_exec(&cb);
+						end
+					end
+				end
+
+				@hookList.each do |hook|
+					hook.consume_event(evt, data);
+				end
+			end
+
+			# @private
+			def handle_phase_change
+				@phaseTime = 0;
+
+				return unless @phasePrepMap[@handler.gamePhase]
+				@phasePrepMap[@handler.gamePhase].each do |cb|
+					instance_exec(&cb);
+				end
+			end
+
+			# @private
+			def handle_game_tick(dT)
+				phase = @handler.gamePhase
+				return unless @phaseMap[phase];
+				return if phase == :idle;
+
+				@phaseLastTime = @phaseTime;
+				@phaseTime += dT;
+				@handler.mqtt.publish_to "Lasertag/Game/Timer", @phaseTime
+
+				instance_exec(dT, &@phaseMap[phase]);
+			end
+		end
+	end
+end