Skinning Entities with Overlays - bryanedds/Nu GitHub Wiki

Overlays

Overlays accomplish two extremely important functions in Nu. First, they reduce the amount of stuff written out to (and consequently read in from) simulant serialization files such as .nugroup files. Second, they provide the user with a way to abstract over property values that multiple entities hold in common. User-defined overlays, called Overlay Routes, are defined in a file that is included with every new Nu game project called Overlayer.nuol. Additionally, for every dispatcher and facet type that the engine discovers, an Overlay Route with a matching name is defined with values set to the type’s properties and default values.

Let’s look at the OmniBlade project’s overlay definitions in Overlayer.nuol –

[[OmniButtonOverlay
  [ButtonOverlay]
  [ButtonDispatcher]
  [ClickSoundOpt [Some [Gui Affirm](/bryanedds/Nu/wiki/ClickSoundOpt-[Some-[Gui-Affirm)]
   [DownOffset [0 -3]]
   [DownImage [Gui ButtonDown]]
   [Font [Gui Font]]
   [FontSizing [Some 24]]
   [TextColor #FFFFFFFF]
   [TextDisabledColor #C0C0C0C0]
   [UpImage [Gui ButtonUp]]]]
 [OmniTextOverlay
  [TextOverlay]
  [TextDispatcher]
  [Font [Gui Font](/bryanedds/Nu/wiki/Font-[Gui-Font)
   [FontSizing [Some 24]]
   [TextColor #FFFFFFFF]
   [TextDisabledColor #C0C0C0C0]]]
 [OmniToggleButtonOverlay
  [ToggleButtonOverlay]
  [ToggleButtonDispatcher]
  [Font [Gui Font](/bryanedds/Nu/wiki/Font-[Gui-Font)
   [FontSizing [Some 24]]
   [PressedOffset [0 -3]]
   [TextColor #FFFFFFFF]
   [TextDisabledColor #C0C0C0C0]
   [ToggledOffset [0 -3]]
   [ToggleSoundOpt [Some [Gui Affirm]]]]]
 [OmniRadioButtonOverlay
  [RadioButtonOverlay]
  [RadioButtonDispatcher]
  [Font [Gui Font](/bryanedds/Nu/wiki/Font-[Gui-Font)
   [FontSizing [Some 24]]
   [PressedOffset [0 -3]]
   [TextColor #FFFFFFFF]
   [TextDisabledColor #C0C0C0C0]
   [DialedOffset [0 -3]]
   [DialSoundOpt [Some [Gui Affirm]]]]]]

The first field, OmniButtonOverlay, is the name of the Overlay Route.

The second field, [ButtonOverlay], is the list of overlays that the overlay will inherit properties from. This list is composed of a single ‘intrinsic’ overlay composed of the default properties of the ButtonDispatcher. It’s called an ‘intrinsic’ overlay because it is automatically created by the engine.

The third field, [ButtonDispatcher], is the list of dispatchers that the overlay will be automatically applied to. The remaining list is the set of properties that will be overlaid and their overlaid values.

Overlays avoid significant duplication while allowing changes to them to automatically propagate to the entities to which they are applied. This sort of functionality is similar to Unity's Prefabs, but is a weaker form that doesn't deal with families of entities. Overlays are more like 'skins' or 'themes' for your game. For something more like Unity's Prefabs, we provide the Structural Entity Propagation System as described here - https://github.com/bryanedds/Nu/wiki/Entity-Structure-Propagation-(Prefab%E2%80%90Like-Behavior)

Overlay.nuol Syntax

WIP