Signal docs update

.github/workflows/main.yml

@@ -9,8 +9,8 @@ on:
       - 'Documentation/**'
       - '*.md'
 
-env:
-  UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+env: 
+  UNITY_LICENSE: "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root>\n    <License id=\"Terms\">\n        <MachineBindings>\n            <Binding Key=\"1\" Value=\"c2c51cf86c7548ec9172c33ee4fe8905\"/>\n            <Binding Key=\"2\" Value=\"c2c51cf86c7548ec9172c33ee4fe8905\"/>\n        </MachineBindings>\n        <MachineID Value=\"jGOG/gpCyVVRuO7sOft8/fNr4PI=\"/>\n        <SerialHash Value=\"20d8e17fa85bafcd88b26e364803e5b088655823\"/>\n        <Features>\n            <Feature Value=\"33\"/>\n            <Feature Value=\"1\"/>\n            <Feature Value=\"12\"/>\n            <Feature Value=\"2\"/>\n            <Feature Value=\"24\"/>\n            <Feature Value=\"3\"/>\n            <Feature Value=\"36\"/>\n            <Feature Value=\"17\"/>\n            <Feature Value=\"19\"/>\n            <Feature Value=\"62\"/>\n        </Features>\n        <DeveloperData Value=\"AQAAAEY0LTUzMkMtODM2Si1VVzJKLVRKR1EtQVY4Rg==\"/>\n        <SerialMasked Value=\"F4-532C-836J-UW2J-TJGQ-XXXX\"/>\n        <StartDate Value=\"2017-12-20T00:00:00\"/>\n        <UpdateDate Value=\"2020-01-26T15:24:01\"/>\n        <InitialActivationDate Value=\"2017-12-20T19:29:43\"/>\n        <LicenseVersion Value=\"6.x\"/>\n        <ClientProvidedVersion Value=\"2019.3.0f1\"/>\n        <AlwaysOnline Value=\"false\"/>\n        <Entitlements>\n            <Entitlement Ns=\"unity_editor\" Tag=\"UnityPersonal\" Type=\"EDITOR\" ValidTo=\"9999-12-31T00:00:00\"/>\n        </Entitlements>\n    </License>\n<Signature xmlns=\"http://www.w3.org/2000/09/xmldsig#\"><SignedInfo><CanonicalizationMethod Algorithm=\"http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments\"/><SignatureMethod Algorithm=\"http://www.w3.org/2000/09/xmldsig#rsa-sha1\"/><Reference URI=\"#Terms\"><Transforms><Transform Algorithm=\"http://www.w3.org/2000/09/xmldsig#enveloped-signature\"/></Transforms><DigestMethod Algorithm=\"http://www.w3.org/2000/09/xmldsig#sha1\"/><DigestValue>srmRlNuh0XDH54JucaFTVJIy7xs=</DigestValue></Reference></SignedInfo><SignatureValue>JdxmcngUM8jp1u+uZuLsp8SGiQr+xyJUEfVK/GTFJibVgKkyx9G2P35auCkvlK2Q4jAvcmtPwURn\nUfqDM+29Afv9UoA6T+XjixjpXrFZAr/7ymMMTSCdm0ifczWwoAOS0QnZp03PWTlujUHJhBw27TZe\nc9qI4R8QFRCJ54AgXsN1Vlfqg4EGwQTDoVSAz3XJuTVkdWvcbJpghDLKmu/WW+vfDjif21o4S7et\nX+Eq9BB24V6oTdxgM++wpDhKd4K1NEfaaqct55ONPbWfuzoPVknV3267eHG4+CpTn0LwZo2K7gd9\nEn2aWqxPn/mvKrHTUfGTOWtOoUOgqkleDxVF9A==</SignatureValue></Signature></root>"
 
 jobs:
   buildAndTestForSupportedPlatforms:

Documentation/Signals.md

@@ -11,6 +11,7 @@
     * <a href="#signalbusinstaller">SignalBusInstaller</a>
     * <a href="#when-to-use-signals">When To Use Signals</a>
 * Advanced
+    * <a href="#abstract-signals">Abstract Signals</a>
     * <a href="#use-with-subcontainers">Signals With Subcontainers</a>
     * <a href="#async-signals">Asynchronous Signals</a>
     * <a href="#settings">Signal Settings</a>
@@ -479,6 +480,151 @@ These are just rules of thumb, but useful to keep in mind when using signals.  T
 
 When event driven program is abused, it is possible to find yourself in "callback hell" where events are triggering other events etc. and which make the entire system impossible to understand.  So signals in general should be used with caution.  Personally I like to use signals for high level game-wide events and then use other forms of communication (unirx streams, c# events, direct method calls, interfaces) for most other things.
 
+## <a id="abstract-signals"></a>Abstract Signals
+
+One of the problems of the signals is that when you subscribe to their types you are coupling your concrete signal types to the subscribers
+
+For example, Lets say I have a player and i want to save the game when i finish a level.
+Ok easy, I create ``SignalLevelCompleted`` and then I subscribe it to my ``SaveGameSystem``
+then I also want to save when i reach a checkpoint, again i create ``SignalCheckpointReached``
+and then I subscribe it to my ``SaveGameSystem``
+you are begining to get something like this...
+```csharp
+public class Example
+{
+   SignalBus signalBus;
+   public Example(Signalbus signalBus) => this.signalBus = signalBus;
+
+   public void CheckpointReached() => signalBus.Fire<SignalCheckpointReached>();
+
+   public void CompleteLevel() => signalBus.Fire<SignalLevelCompleted>();
+}
+
+public class SaveGameSystem
+{
+   public SaveGameSystem(SignalBus signalBus)
+   {
+      signalBus.Subscribe<SignalCheckpointReached>(x => SaveGame());
+      signalBus.Subscribe<SignalLevelCompleted>(x => SaveGame());
+   }
+
+   void SaveGame() { /*Saves the game*/ }
+}
+
+//in your installer
+Container.DeclareSignal<SignalLevelCompleted>();
+Container.DeclareSignal<SignalCheckpointReached>();
+
+//your signal types
+public struct SignalCheckpointReached{}
+public struct SignalLevelCompleted{}
+```
+
+And then you realize you are coupling the types``signalLevelCompleted`` and ``SignalCheckpointReached``to ``SaveGameSystem``. 
+``SaveGameSystem`` shouldn't know about those "non related with saving" events...
+
+So let's give the power of interfaces to signals!
+So i have the ``SignalCheckpointReached`` and ``SignalLevelCompleted`` both implementing **``ISignalGameSaver``**
+and my ``SaveGameSystem`` just Subscribes to **``ISignalGameSaver``** for saving the game
+So when i fire any of those signals the ``SaveGameSystem`` saves the game.
+Then you have something like this...
+```csharp
+public class Example
+{
+   SignalBus signalBus;
+   public Example(Signalbus signalBus) => this.signalBus = signalBus;
+
+   public void CheckpointReached() => signalBus.AbstractFire<SignalCheckpointReached>();
+
+   public void CompleteLevel() => signalBus.AbstractFire<SignalLevelCompleted>();
+}
+
+public class SaveGameSystem
+{
+   public SaveGameSystem(SignalBus signalBus)
+   {
+      signalBus.Subscribe<ISignalGameSaver>(x => SaveGame());
+   }
+
+   void SaveGame() { /*Saves the game*/ }
+}
+
+//in your installer
+Container.DeclareSignalWithInterfaces<SignalLevelCompleted>();
+Container.DeclareSignalWithInterfaces<SignalCheckpointReached>();
+
+//your signal types
+public struct SignalCheckpointReached : ISignalGameSaver{}
+public struct SignalLevelCompleted : ISignalGameSaver{}
+
+public interface ISignalGameSaver{}
+```
+
+Now your ``SaveGameSystem`` doesnt knows about CheckPoints nor Level events, and just reacts to signals that save the game.
+The main difference is in the Signal declaration and Firing
+ - ``DeclareSignalWithInterfaces`` works like ``DeclareSignal`` but it declares the interfaces too.
+ - ``AbstractFire`` is the same that ``Fire`` but it fires the interfacesjust if you have Declared the signal with interfaces 
+ otherwise it will throw an exception.
+
+Ok, let's show even more power.
+Now i create another signal for the WorldDestroyed Achievement "SignalWorldDestroyed"
+But i also want my SoundSystem to play sounds when i reach a checkpoint and/or unlock an Achievement
+So the code could look like this.
+```csharp
+public class Example
+{
+   SignalBus signalBus;
+   public Example(Signalbus signalBus) => this.signalBus = signalBus;
+
+   public void CheckpointReached() => signalBus.AbstractFire<SignalCheckpointReached>();
+
+   public void DestroyWorld() => signalBus.AbstractFire<SignalWorldDestroyed>();
+}
+
+public class SoundSystem
+{
+   public SoundSystem(SignalBus signalBus)
+   {
+      signalBus.Subscribe<ISignalSoundPlayer>(x => PlaySound(x.soundId));
+   }
+
+   void PlaySound(int soundId) { /*Plays the sound with the given id*/ }
+}
+
+public class AchievementSystem
+{
+   public AchievementSystem(SignalBus signalBus)
+   {
+      signalBus.Subscribe<ISignalAchievementUnlocker>(x => UnlockAchievement(x.achievementKey));
+   }
+
+   void UnlockAchievement(string key) { /*Unlocks the achievement with the given key*/ }
+}
+
+//in your installer
+Container.DeclareSignalWithInterfaces<SignalCheckpointReached>();
+Container.DeclareSignalWithInterfaces<SignalWorldDestroyed>();
+
+//your signal types
+public struct SignalCheckpointReached : ISignalGameSaver, ISignalSoundPlayer
+{ 
+   public int SoundId { get => 2} //or configured in a scriptable with constants instead of hardcoded
+}
+public struct SignalWorldDestroyed : ISignalAchievementUnlocker, ISignalSoundPlayer
+{
+   public int SoundId { get => 4}
+   public string AchievementKey { get => "WORLD_DESTROYED"}
+}
+
+//Your signal interfaces
+public interface ISignalGameSaver{}
+public interface ISignalSoundPlayer{ int SoundId {get;}}
+public interface ISignalAchievementUnlocker{ string AchievementKey {get;}}
+```
+
+It offers a lot of modularity and abstraction for signals,
+you fire a concrete signal telling what you did and give them functionality trough Interface implementations
+
 ## <a id="use-with-subcontainers"></a>Signals With Subcontainers
 
 Signals are only visible at the container level where they are declared and below.  For example, you might use Unity's multi-scene support and split up your game into a GUI scene and an Environment scene.  In the GUI scene you might fire a signal indicating that the GUI popup overlay has been opened/closed, so that the Environment scene can pause/resume activity.  One way of achieving this would be to declare a signal in a ProjectContext installer (or a shared <a href="../README.md#scene-parenting">scene parent</a>), then subscribe to it in the Environment scene, and then fire it from the GUI scene.