@@CrysisMod
<TITLE GameMod>
    <P>

@@Overview
A GameMod is used to extend the GameDLL to new
functionalities.



The core of the GameMod is the implementation of the IGame
interface. By doing so, the game intialization and update
functions can even be used to add completely new game
systems.



The GameMod also is the location to extend existing game
systems. Examples would be the following items:



    * entity class
    * flow nodes
    * game rules
    * items/weapons
    * vehicle modules (movements, parts, damage behaviors,
      etc)

@@Creating a new GameMod
The easiest way to create a new GameMod is to use the BaseMod
SDK sample as template and to extend its functionalities.



The BaseMod sample is located in the following directory of
the CryEngine SDK:

<I>Mods/Base/</I>



We recommand to copy all the files from this sample before
starting to modify it.



The BaseMod is a stripped down copy of the GameDLL which was
supplied with Crysis. The code was adapted to be able to run
as a mod from the GameDLL.



The entry point for the GameMod is the following function:

<C>GAME_API IGame *</C><LINK IGame::TEntryFunction, CreateGame><C>(IGameFramework*
pGameFramework)</C>



The purpose of the CreateGame function is to instantiate the
IGame interface and to save the pointer of the ISystem
interface for the CryEngine instance.

@@Loading a GameMod
The Editor and the Launcher can receive the "game" argument
which specify a GameMod to be loaded. For example, starting
the launcher like this <I>"launcher game BaseMod"</I> will
start CryEngine with the BaseMod.



A GameMod is loaded from the IGameStartup implementation
inside of GameDLL.



The function <LINK IGameStartup::Init@SSystemInitParams &, IGameStartup::Init>
will search for the entry function which creates a new
instance of the IGame implementation stored in the GameMod.



@@Implementing a new Game Object extension in C++
* Using the helper template *
The CGameObjectExtensionHelper template can be used to
simplify the implementation of a GameObjectExtension. This
helper template will handle the RMI functionality of the
extension interface.



This template is included inside of the header file
IGameObject.h. To use the helper class, the declaration need
to follow this example:



<C>class CNewGameObjectExt : public
CGameObjectExtensionHelper\<CNewGameObjectExt,
IGameObjectExtension\></C>



The important functions to implement the most basic game
object extension are the following:


<TABLE>
Functions                                                                                     Descriptions
--------------------------------------------------------------------------------------------  -------------------------------------------------------------------------------------------------------------
<LINK IGameObjectExtension::Init@IGameObject *, IGameObjectExtension::Init>                   The Init function should set the member
                                                                                               values and validate with the return
                                                                                               value if the initialization is
                                                                                               succesful. If needed, resources should
                                                                                               be allocated during the execution of the
                                                                                               Init.
<LINK IGameObjectExtension::PostInit@IGameObject *, IGameObjectExtension::PostInit>           The ideal location to set the initial
                                                                                               update slot state (more information can
                                                                                               be found in <LINK IGameObject::EnableUpdateSlot@IGameObjectExtension *@int, IGameObject::EnableUpdateSlot>).
<LINK IGameObjectExtension::Release>                                                          This function should release any
                                                                                               resource previously allocated by the
                                                                                               extension. Additionally, the Release
                                                                                               function need to free the object
                                                                                               instance.
<LINK IGameObjectExtension::Serialize@TSerialize@unsigned, IGameObjectExtension::Serialize>   Any critical state variables needs to be
                                                                                               serialized, both for disc serialization
                                                                                               (ie: save games) or network
                                                                                               serialization.
<LINK IGameObjectExtension::Update@SEntityUpdateContext&@int, IGameObjectExtension::Update>   Any frame rate dependent updates should
                                                                                               be implemented part of this function.
</TABLE>

@@Implementing a game rules



@@Implementing a new Weapon class
* Overview *
A weapon is an item which contains the three following
components: a weapon class, a fire mode and an ammunition
class. The core functionalities are implemented in C++, but
these components read the data stored inside xml files of the
weapon script folder in Game/Scripts/Entities/Items/Weapons.



* Weapon class *


A new weapon class can be added by implementing the IItem and
IWeapon interfaces. A basic weapon implementation is supplied
in the Crysis GameDLL which provide the most commonly
required weapon functionality.



When implementing a new weapon class, it's recommanded to
derive from the CWeapon class. The following functions from
CWeapon are the most common ones overrided to provide new
gameplay functionalities.


<TABLE>
Functions                                                                 \Description
------------------------------------------------------------------------  --------------------------------------------------
<LINK IItem::OnAction@EntityId@const char *@int@float, IItem::OnAction>   CWeapon already implements the common weapon
                                                                           action possibles like attack, reload, zoom and
                                                                           changing the fire mode. A new weapon requiring
                                                                           new actions from the player should override this
                                                                           function.
<LINK IItem::Select@bool, IItem::Select>                                  This function is called when the actor
                                                                           select/unselect the weapon as his current item.
                                                                           Any code which modifies the camera/rendering
                                                                           settings should be placed in this function.
CItem::CanPick(CanPickUp)                                                 The CItem implementation will make sure that the
                                                                           action does not already carry this weapon. When
                                                                           overridering this function, it is possible to add
                                                                           \conditions which rule if the actor is allowed to
                                                                           pickup the weapon.
<LINK IItem::PickUp@EntityId@bool@bool@bool, IItem::PickUp>               Should handle adding the weapon to the actor
                                                                           inventory.<P>
                                                                           <P>
                                                                           Please note that after CItem::PickUp has been
                                                                           called, it's no longer possible to refuse the
                                                                           actor from picking up the weapon. The appropriate
                                                                           code to validate the actor from taking the weapon
                                                                           should be placed in the CanPick() function.
</TABLE>


* Fire mode class *


Crysis already includes the following fire mode: Automatic,
Beam, Burst, Charge, Detonate, Energise, Freezing Beam, Heal,
Melee, Plant, Rapid, Repair, Scan, Shotgun, Single, Tactical
and Throw.



In case all these fire mode aren't sufficient, it's possible
to implement a new fire mode by deriving the IFireMode
interface.



In most of the cases, deriving from the existing CSingle
class should simplify this process. If this approach is
followed, the following functions are usually to only ones
needed to override.


<TABLE>
Functions                                                    \Description of the functionalities
                                                              already provided by CSingle
-----------------------------------------------------------  ---------------------------------------
<LINK IFireMode::Activate@bool, IFireMode::Activate>         Triggers the appropriates effects and
                                                              sounds, resets state variables.
<LINK IFireMode::CanFire@bool@const, IFireMode::CanFire>     Performs various tests to be sure
                                                              ammunitions are still available and
                                                              that the weapon isn't overheating.
<LINK IFireMode::CanReload@const, IFireMode::CanReload>      Search the in inventory to be sure the
                                                              actor carries the clips for ammunition
                                                              required.
<LINK IFireMode::StartFire@EntityId, IFireMode::StartFire>   Triggers the appropriates effects and
                                                              sounds, performs hit computations
<LINK IFireMode::Update@float@uint, IFireMode::Update>       Performs various frame dependent
                                                              computations for different weapon
                                                              features including auto-aim, zoom,
                                                              recoil and heat accumulation.
</TABLE>


* Projectile class *


The CProjectile class implemented in the Crysis GameDLL
provide most of the functionalities needed. It's possible to
extend this class by deriving from it, for example to
implement new functionalities to homing missile or to have
new class of explosives.



When deriving from CProjectile, the following functions
should be able to give enough flexibilities to expand its game
play features.


<TABLE>
Functions                                                                                             Descriptions
----------------------------------------------------------------------------------------------------  ----------------------------------
<LINK IGameObjectExtension::HandleEvent@const SGameObjectEvent&, IGameObjectExtension::HandleEvent>   Function used to handle game
                                                                                                       events, the ideal location to
                                                                                                       deal with collisions.
<LINK CProjectile::Launch@const Vec3 &@const Vec3 &@const Vec3 &@float, CProjectile::Launch>          Provides a way to adjust or setup
                                                                                                       any functionality before the
                                                                                                       projectile is shot by the weapon.
<LINK CProjectile::Update@SEntityUpdateContext &@int, CProjectile::Update>                            After the projectile was
                                                                                                       launched, this function is called
                                                                                                       at every frame until the
                                                                                                       projectile reach its destination.
<LINK CProjectile::SetDestination@const Vec3&, CProjectile::SetDestination(const Vec3& pos)>          If the weapon has any auto-aiming
                                                                                                       capabilities, this function will
                                                                                                       be called with the world position
                                                                                                       of the target.
<LINK CProjectile::SetDestination@EntityId, CProjectile::SetDestination(EntityId targetId)>           If the weapon has any auto-aiming
                                                                                                       capabilities, this function will
                                                                                                       be called with entity id of the
                                                                                                       locked target.
</TABLE>
