S2ENGINE HD  1.4.6
Official manual about S2Engine HD editor and programming
The Player Character

The player Character is the main element of the EasyGame pack. It owns an HUD inventory and manage it.

Player can perform a bunch of actions such as swimming, drive, turn off/on a lamp light, picking object using camera.
All these actions are notified using events, for example if player enter water and starts to swim an event PLAYER_START_SWIM is sent to its GameMachine FSM. In this way you can process these events as you want to build your player logic

HUD

Player Character is provided with a complex integrated HUD management system that also implements an inventory system. In order to make player character recognizing the HUD elements you must assign specific names to HUD elements basing on their behaviour.

Note
All the HUD elements can be omitted or inserted basing on your needs. The player character automatically manages only the extisting HUD elements.

As said Player also manages an internal inventory showing it on the HUD when pressing a button. User can specify what button must be pressed by using the parameter ActionCommand.

The following is the pre-made HUD provided with the demo project and assets pack. In the image HUD element names are specified:

hud.jpg
  1. inventory: The inventory container. It must be of class "frame" (see widgetClass parameter in Widget Objects) and It must contains all the inventory elements. It is showed/hided by the player by using the ActionCommand
  2. target: The player HUD cross, it is needed for aiming and/or picking objects (can be a label or a button)
  3. targetText: This is a label or button used to specify what action must be done when player aims an object. The name of the action depends on the class of aimed object (for example switch has open/close actions, itemTAG has take action, etc..)
  4. targetCaption: This is a label / button that contains the textual description of the aimed object. The description can exists or not depending on object class. In the case of ItemTAGs for example the description can be specified into the ItemCaption parameter
  5. item_caption: This is a label / button that contains the same textual description contained into the targetCaption but this time it is showed into the inventory when an item / weapon is selected
  6. inventory_weapons_tag: this is a button used to denote to user that weapons table of the inventory has been selected
  7. inventory_items_tag: this is a button used to denote to user that items table of the inventory has been selected
  8. item_slot0,item_slot1,..n: these are the slots in which player puts the items icons, can be buttons. They are enumerated from 0 to n, where n depends on how many HUD elements you put BUT it must be less than 20. NOTE that you must also specify the maximum number of items into the player character parameter maxNumSlots
  9. item_slot_count0,item_slot_count1,..n: These are labels that show the number of items of a given type available into the player inventory. The max count depends on the item and can be specified into the MaxCount parameter of the Item prefab. Also you can specify that the item can be used indefinitely by making TRUE the unlimitedUse parameter of the corresponding itemTAG.
  10. weap_slot0,weap_slot1,..n: these are the slots in which player puts the weapon icons, can be buttons. They are enumerated from 0 to n, where n depends on how many HUD elements you put BUT it must be less than 20. NOTE that you must also specify the maximum number of items into the player character parameter maxNumWeapons
  11. health: the health indicator. Usually it can be a progressBar widget class
  12. health_icon: a label containing an image representing the health. It is only decorative. If you insert it and make TRUE the outlineLowHealth parameter of playerCharacter it becomes RED when health go low.
  13. health_border: a label containing an image for the border of the health indicator. It is only decorative. Just like health_icon if you insert it and make TRUE the outlineLowHealth parameter of playerCharacter it becomes RED when health go low.
  14. ammo: the ammo container, must be a frame. It contains the weapon projectiles and weapon loaders counters
  15. ammo_projs: the weapon projectiles counter
  16. ammo_loads: the weapon loaders counter
  17. mission: This is a label indicating the current mission. Mission textual description must be specified inside the Description parameter of the mission object
  18. goal_0,goal_1,..n: these are buttons (or labels) containing the description of sub-missions. Sub-missions are complementary goals related to a mission, they can be mandatory or optional depending on how you want to design your level.
Note
The previous image is referred to the HUD section of the whole EasyGame Pack pre-made game GUI, which contains other elements (such as game menu, game-over screen, etc..) that has been hided in this case. To show only a part of the overall GUI in S2ENGINE HD GUI editor you must select the elements you want to show (sub-elements are automatically showed if you select a container element) and then click on ShowSelected button:
showSelected.jpg

Player Input Commands

Messages and Events

The player character interfaces directly with its GameMachine FSM by sending events and receiving messages. For example when a player enter a car it sents the event ENTER_VEHICLE to its FSM. In this section we will explain all the events and messages the player character can receive and send.

Note
playerCharacter also send messages for making them to be received by scripts. They are the same as events for FSM.

Player Receiving Messages

PlayerCharacter do some actions replying to messages that are sent to it. For example if we sent a message "decrementHealth" to the playerCharacter we will see the HUD health indicator to decrease. Messages can be sent by FSM GameMachine using the action sendMessage. In the sendMessage action you can specify:

  • MessageName: name of the message, in the example "DecrementHealth"
  • MessageContent: the content of the message if any. in the case of "DecrementHealth" message the content is the amount of energy to decrease
Note
Not all messages must be explicitly sent by FSM, some of them are automatically sent to player by various subsysems or other objects.

The following are all the messages the playerCharacter process when receive them:

  • EnterWater: It is a reserved message. It cannot explicitly sent by gameMachine FSM. It is sent by physics system when player enters water
  • ExitWater: It is a reserved message. It cannot explicitly sent by gameMachine FSM. It is sent by physics system when player exits water
  • ENTER_VEHICLE: It cannot explicitly sent by gameMachine FSM. It is sent to player when it pick a vehicle and performs the action command.
  • EXIT_VEHICLE: It cannot explicitly sent by gameMachine FSM. It is sent to player when it is just inside a vehicle and performs the action command.
  • selectWeapon: when playerCharacter receives this message it shows the weapon specified into the content and hides all the others. Also It sends an event to its FSM called "weapon_"+weaponName, where weaponName is the name of the selected weapon. This is a way to make FSM knowing what is the weapon in use. The weaponName is the name of the weapon object attached to the player model (see Weapons).
  • USE_ITEM: you can send this message when you want to force the player using a specified item. The content contains the item prefab player needs to recognize the item into the inventory. (see Items for more info about how items are used)
  • UNLOCK_ITEM: items can be locked, i.e. they cannot be used even if selected into the inventory. When you want to unlock a locked item you must send this message to player specify the item prefab into the message content. (see Items for more info about how items are used)
  • HIDE_WEAPON: send this message if you want to hide the current weapon (for example when player enters a vehicle). in the content the name of the weapon object. If you want to show the hided weapon send selectWeapon message.
  • USE_WEAPON: send this message when you want force the player to change the current weapon with the specified one. the content must contain the name of the weapon object.
  • TAKE: it is sent automatically by itemTAGs objects when player character pick them. This automatically inserts the related item into the inventory.
  • ARM: it is sent automatically by WeaponTAGs objects when player character pick them. this automatically inserts the related weapon into the inventory
  • SUPPLY_AMMO: it is sent automatically by WeaponAmmoTAGs objects when player character pick them. This automatically fill the related weapon AMMO
  • RechargeBattery: It must be sent by FSM when you want the player recharge the battery of Lamp light. battery duration is specified by batteryDuration parameter of player character
  • IncrementHealth: It must be sent by FSM when you want the player increment its health. The content must be the amount of health of player (between 0 and maxHealth)
  • DecrementHealth: It must be sent by FSM when you want the player decrement its health. The content must be the amount of health of player (between 0 and maxHealth)
  • LampON: It must be sent by FSM when you want the player turn ON the lamp light
  • LampOFF: It must be sent by FSM when you want the player turn OFF the lamp light
  • ActionToPerform: It cannot explicitly sent by gameMachine FSM. This message is sent by the AIMED object for making player to know what action to perform (open/close, take, etc..). These messages are sent by ItemTAGs, weaponTAGs, weaponAmmoTAGs, Vehicles and Switches class objects.

Player Sending Events

The following are events that player (or other objects) sends to its FSM (and interacting objects FSM) when something happens (a pressed button, an item picking, etc..)

Note
these events must be added (if they don't exists) to the GameMachine system (see Events).
  • SHOW_INVENTORY: it is sent to player FSM when user press the inventoryCommand to show the inventory.
  • HIDE_INVENTORY: it is sent to player FSM when user press the inventoryCommand to hide the inventory.
  • MENU_SHOWED: it is sent when to player FSM user press the menuCommand to show the menu.
  • MENU_HIDED: it is sent when to player FSM user press the menuCommand to hide the menu.
  • PLAYER_START_SWIM: it is sent to player FSM when player must start to swim, i.e. it enters a lake/sea area.
  • PLAYER_END_SWIM: it is sent to player FSM when player must end to swim, i.e. it exit from lake/sea area.
  • CAMERA_ENTER_WATER: it is sent to player FSM when the player camera enters a lake/sea area.
  • CAMERA_EXIT_WATER: it is sent to player FSM when the player camera exits from lake/sea area. It is useful to start the wet camera effect.
  • CHANGE_WEAPON: it is sent to player FSM when a weapon is selected from inventory or when the ChangeWeaponAxis command is performed. See Weapons
  • TARGET_AIMED: it is sent to player FSM when it aims an interacting object (the target, for example a switch, an iemTAG, a vehicle, ...). See also Items and Weapons
  • ACTION: it is sent to the aimed target when player performs the acion command (i.e. user press action button). See also Items and Weapons
  • AIMED: it is sent to target object FSM when it aims an interacting object (the target, for example a switch, an iemTAG, a vehicle, ...). See also Items and Weapons
  • DIE: It is sent when player reaches 0 health
  • Weapon_weaponName: It is sent to player FSM after a weapon is selected,changed and showed. It is needed to know the current player weapon. WeaponName is the name of the weapon object attached to player model. See Weapons

Picking

The player character automatically performs picking of the interactive elements of the scene.

There are 2 ways the player can interact with scene objects:

  • By Range: player interact with all objects inside a specified range. The range can be specified with ActionRange parameter of playerCharacter
  • By Aiming: player can interact with objects aimed by its camera. In this case the camera object must be specified into the camera parameter of PlayerCharacter

The first mode is usually used in 3rd person games, the second in first person games. By default player uses the By Aiming mode, but you can switch to By Range mode by put TRUE the ActionByRange parameter of player character Usually the interaction works in the following steps:

  1. Player aims an object (or goes close to the object)
  2. User press the action button

The action button can be specified in the ActionCommand parameter of the player character. It is an input action reference that can be configured using Input Mapping.
You can also choose to make player performing actions without pressing any button by put AutoAction parameter to TRUE. This could be the case, for example, when you want to make an FPS in which player can take health simply by passing trough the health TAG.

The objects that can interact with player are ones belonging to the following classes:

  • switch: included into S2BasePack dll. Note that EventSwitch, AwakeSwitch, ActivationSwitch, MusicSwitch, ShowSwitch are all derived from Switch class, so they also can interact with player character
  • itemTAG: included into S2GamePack dll.
  • weaponTAG: included into S2GamePack dll.
  • vehicle: included into S2BasePack dll
  • weaponAmmoTAG: included into S2GamePack dll.

When a player aims one of these objects it sends to the aimed object an AIMED event (also a message) (see Player Sending Events).

Note
in the case of By Range mode this doesn't happen.

The aimed object replies to player character with an ActionToPerform message (see Player Receiving Messages) that makes player to show what to do on the HUD (see HUD). Then, if user presses the action button, player character sends, to the aimed object, an ACTION event (also a message), that, depending on the object class produces different results:

  • In the case of ItemTAG the related Item is added to player inventory (see ItemObject and ItemTAG).
  • In the case of WeaponTAG the related weapon is added to inventory
  • In the case of WeaponAmmoTAG the related weapon ammo count is incremented
  • In the case of Switch it opens if closed or closes if opened
  • In the case of Vehicle an ENTER_VEHICLE event is sent to player character

Drop items/weapons

Player can also drop items and/or weapons from inventory.
In this case the item slot count is decremented and the related itemTAG is instanced again into the scene, or, in the case of weapon, the weapon slot is empty and the related weaponTAG is re-spawned into the scene.
To make playerCharacter re-instancing the itemTAG / weaponTAG it is needed you create an itemTAG or weaponTAG prefab and put a reference to it from itemObject prefab or weapon, setting the TagPrefab parameter (see Items, Weapons).