Home

Configuration Options

Command line options and tools

Running core.exe from command line

core.exe can be invoked either via the GamesManager or directly via the command line. For ease of debugging command line parameters can also be placed in a params.txt file in the MGDF root directory (the contents of this file will have preference over anything specified on the command line)

-logLevel
[Optional] Allows you to specify the logging verbosity, possible values in descending order of verbosity log_low|log_medium|log_high|log_error
-userdiroverride
[Optional] If specified, the directory from which to load and save user specific data to (save games/preferences etc.) will be either the gamesdir override (if specified) or application directory. If this parameter is omitted, the data directory will be the users appData\Local\MGDF\uid folder
-gamediroverride
[Optional] Allows you to specify a directory from which to load games from (by default this is the core.exe's application /game subdirectory)

Running GamesManager.exe from command line

GamesManager.exe run without any arguments will check for updates and launch the game in its /game folder. However it also has a couple of arguments which can be useful to run as part of a games installer such as NSIS

-register
[Optional] In order to make installing/uninstalling your game easier. When invoked will install any framework dependencies (for example the Visual C++ runtime), as well as any installed program registry entries, desktop shortcuts, start menu shortcuts and windows games explorer integration required.
-deregister
[Optional] Removes anything added via the register argument (with the exception of framework dependancies)
-userdiroverride
[Optional] If specified, the directory from which to load and save user specific data to (save games/preferences etc.) will be either the gamesdir override (if specified) or application directory. If this parameter is omitted, the data directory will be the users appData\Local\MGDF\uid folder
-gamediroverride
[Optional] Allows you to specify a directory from which to load games from (by default this is the core.exe's application /game subdirectory)
-noupdatecheck
[Optional] Disables any checking for updates before launching

PackageGen.exe

PackageGen.exe is a tool supplied in the SDK (Found in the Bin folder of the SDK) and allows you to create MGDF game packages or create a game update package based upon the difference between two existing game packages. Packages created by this tool can then be posted for download by the GamesManager as updates. Full game packages are simply a zip file containing the contents of the /game folder. Game update packages are similar, though they include an extra update.json file which specifies which old files should be removed before installing, and only includes files which have changed since the last full package was installed - as such they typically result in smaller download sizes.

Usage

PackageGen "framework /game folder" -o "game package file"

Creates a new installer package from a directory.

PackageGen -u "older game package file" "newer game package file" -o "game update package file"

Creates a new update installer package that contains the differences between the old version to the new one.

Example output
Creating installer package
Creating install package c:\users\glenn\desktop\game.zip ...........
Validating installer package c:\users\glenn\desktop\game.zip
Installer package created
    Version: 0.1
    MD5: bd226dd32804d683348e2708b7288087

Game.json configuration

The game.json file is where all configuration and default preferences for a game is stored. The full schema for a game.json file is as follows

{
    "gameUid":"a unique id",
    "gameName":"A human readable name",
    "version":"0.1",
    "interfaceVersion":"1",
    "developerName":"Human readable developer name",
    "homepage":"http://www.example.com",
    "supportEmail":"[email protected]",
    "supportS3Bucket":"game-crash-reports",
    "supportS3BucketAccessKey":"myawsaccesskey",
    "supportS3BucketSecretKey":"myawssecretkey",
    "updateService":"https://www.example.com/update.json",
    "statisticsService":"https://www.example.com/stats.svc",
    "statisticsPrivacyPolicy":"https://www.example.com/privacy",
    "preferences":{
        "key":"value",
    }
}

Game.json schema

gameUid
[Required] A unique identifier used to partition away game data from other MGDF games. It is important that this value is unique, so we recommend a GUID or similar string which is unlikely to collide with other MGDF games installed on a users system
gameName
[Required] A human readable name of the game. This will be used for any user visible display of the game in the GamesManager user interface
version
[Required] A version string in the format major.minor.revision.build.
interfaceVersion
[Required] The host interface version supported by the module. Currently, this should always be "1"
developerName
[Required] A human readable description of the games developer. This will be displayed when the GamesManager requires the users permission to do something, for example to collect game statistics.
homepage
[Optional] A url to the game's homepage, this will be added to the entry for the game in the Windows installed programs list if provided
supportEmail
[Optional] An email address shown to users when crashes and other errors occur so that they can submit error reports
supportS3Bucket
[Optional] An Amazon S3 Bucket which MGDF can automatically upload crash reports to. If specified this mode of error reporting is used instead of prompting the user to send a report to the support email address.
supportS3BucketAccessKey
[Optional] Access key for an S3 user with access to the support S3 bucket. Note: For security you should ensure this user has the minimum possible permissions, ideally write only access to the support bucket and nothing else.
supportS3BucketSecretKey
[Optional] Secret key for an S3 user with access to the support S3 bucket.
updateService
[Optional] A url used to check for updates (see Update manifest configuration for more information)
statisticsService
[Optional] A url used to post game statistics information to (see Statistics service configuration for more information)
statisticsPrivacyPolicy
[Required if statisticsservice is set] A url containing the privacy policy information for a developer who wishes to collect game statistics. This url is shown to the user when the GamesManager asks thier permission to gather statistics. If it is not specified, then no statistics can be collected
preferences
[Optional] A dictionary of strings specifying any preferences used by the game. These can be accessed via the IMGDFGame Get/Set/HasPreference methods. A number of built in preferences are also used by the MGDF host and are always prefixed with host. The full list of built in preferences is shown below. These built in preferences can be overridden by specifying them in the game.json file.

Built in host preferences

host.musicVolume
A string value between 0 and 1 that sets the volume for all music played using IMGDFSoundStreams. Defaults to "1.0"
host.soundVolume
A string value between 0 and 1 that sets the volume for all sounds played using IMGDFSounds. defaults to "1.0"
host.simFps
The target framerate of the sim thread. If the sim thread is able to run faster than this, the host will add in sleeps between timesteps to ensure that the sim is limited to this framerate (note the render thread framerate is unaffected by this setting). Defaults to "60"
host.renderFps
The target framerate of the render thread. If vsync is disabled or the refresh rate of the monitor is faster, the host will add in sleeps between renders to ensure that the rendering is limited to this framerate (note the sim thread framerate is unaffected by this setting). Not set by default
host.screenX
The desired horizontal resolution to display the game at when running in fullscreen. If this resolution is not possible on the current display, then the native resolution will be used instead. Defaults to "1024"
host.screenY
The desired vertical resolution to display the game at when running in fullscreen. If this resolution is not possible on the current display, then the native resolution will be used instead. Defaults to "768"
host.fullScreen
Whether to start the game in fullscreen ("1") or in windowed mode ("0"). Defaults to "0"
host.fullScreenExclusive
Should fullscreen use exclusive mode ("1") or windowed mode ("0"). Defaults to "0"
host.multiSampleLevel
The desired multisample level to use for the backbuffer, if this is not supported on the current display device, then the next highest level that is supported will be used instead. Defaults to "1"
host.RTMultiSampleLevel
The desired multisample level to use for render target buffers. Modules don't have to use this setting, though it is recommended. Defaults to "1"
host.vsync
Whether or not to use vsync on the render thread ("1"), or whether to render frames fast as possible ("0"). Defaults to "1"
host.windowResize
Whether to allow resizing of the game window in windowed mode ("1") or to have a fixed size window ("0"). This setting is provided as resizing the window may cause a D3D device reset. Because of this, having a resizable window means your game will have to be able to handle this. If you don't want to worry about this, leave it at the default of "0"
host.windowSizeX
The desired horizontal size of the window when in windowed mode. Defaults to "1024"
host.windowSizeY
The desired vertical size of the window when in windowed mode. Defaults to "768"
host.windowPositionX
The desired horizontal position of the window when in windowed mode. Defaults to null (position determined by the OS)
host.windowPositionY
The desired vertical position of the window when in windowed mode. Defaults to null (position determined by the OS)

Game update manifest

The game update manifest file is a json file whose location is specified in the updateservice property of the game.json file. This file is used to determine if updates to a game are available. The full schema for an update manifest file is shown below.

NOTE The GamesManager supports downloading game updates from urls that use http authentication (either basic or digest) if you want to restrict download access to paid users. The GamesManager will pop up a username/password prompt in this case before the update will proceed.

{
  "framework": {
    "version": "0.11.22",
    "url": "https://s3.matchstickframework.org/MGDF_0.11.22_x64.zip",
    "md5": "be4573e2058fa6106093443e6c7857d1"
  },
  "latest": {
    "version": "0.2.4",
    "url": "https://www.example.com/game_0.2.4.zip",
    "md5": "8059891b6663315a72a954c282a963c8"
  },
  "updateOlderVersions": [
    {
      "url": "https://www.example.com/game_0.2.4_update.zip",
      "md5": "eac5db79ad1fa8f61d20283fef37ad33",
      "fromVersion": "0.2.2",
      "toVersion": "0.2.3"
    }
  ]
}

Game update manifest schema

framework
[Optional] Used to specify which version of the MGDF framework the game should use. This is useful as it gives you control over which framework version you want your game to run on and can update the framework as you require. The framework .zip file should be a framework distributable which can be found in the MGDF SDK download
latest
[Required] Specifies the latest version of your game which is available. This zip file must be a game package built by the MGDF SDK PackageGen tool
updateOlderVersions
[Optional] Specifies a list of partial upgrade packages which can upgrade a version fromVersion - toVersion up to the latest version. The partial update zip file should be an update package built by the MGDF SDK PackageGen tool

Statistics service

The MGDF statistics service works by having the GamesManager upload lists of statistics (created by calls to the IStatisticsManager inside a running game) to a restful json web service endpoint specified in a games game.json file. In order to use this feature you will need to implement a compatible web service that implements the methods shown below

Request fields

gameUid
A string value of up to 255 characters in length.
sessionId
A string value of up to 255 characters in length. All statistic key/values should be associated with this session id.
statistics
An array of statistic objects containing the fields below.
  • timestamp An unsigned integer value marking the time the statistic was recorded. The time interval is measured in seconds since the beginning of the current session.
  • name A string value of up to 255 characters in length.
  • value A string value of up to 255 characters in length.

Sample HTTP request to http://example.com/statistics (Note the statisticsservice url in game.json would be http://example.com in this case)

POST http://example.com/statistics HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.com
Content-Length: 146
{"gameUid":"blah","sessionId":"xxxx","statistics":[{"timestamp":0,"name":"key1","value":"value1"},{"timestamp":1,"name":"key2","value":"value2"}]}

Response fields

errors
An array of strings containing any errors caused in processing the request. If the request is successful, this array will be empty.
success
A boolean value that is true if the request was successfully processed, false otherwise.

Sample HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 29
{"errors":[], "success":true}

Functions

There are a number of entrypoint functions which can be exported by a module which are used by the host to create the module instance and to query the requirements of the module.

GetCompatibleFeatureLevels Allows a module to tell the host what D3D11 feature level to try and use when creating the D3D device.

UINT64 GetCompatibleFeatureLevels ( D3D_FEATURE_LEVEL * levels , UINT64 * featureLevelSize )
Parameters
levels An array supplied to the module to fill with acceptable D3D feature levels
featureLevelSize The size of the levels array
Returns
Should return 0 if the supplied levels array is large enough, otherwise should return the size required

GetCustomArchiveHandlers Allows a module to tell the host if it is going to provide any custom virtual file system handlers.

HRESULT GetCustomArchiveHandlers ( IMGDFArchiveHandler ** list , UINT64 * length , IMGDFLogger * logger )
Parameters
list Pointer to a buffer to store the list of provided archive handlers
length The length of the provided buffer
logger An interface allowing the archive handler to write to the MGDF logs
Returns
Should return S_OK if the supplied list is large enough to contain all the items in the list, otherwise return E_FAIL and sets the required size in the length parameter

GetModule Factory function which returns an instance of the module to the host.

HRESULT GetModule ( IMGDFModule ** module )
Parameters
module An instance of the module interface
Returns
Should return S_OK if the module could be created, otherwise E_FAIL

Interfaces

Once the module has been created, it can access the MGDF host's functionality using the following interfaces. Most of these interfaces are not directly accessible to a module, but are instead properties of the ISimHost and IRenderHost interfaces.

IMGDFArchiveHandler Provides an interface for creating portions of the vfs tree from archive files

Inherits from: IUnknown

  • MapArchive Get the root node of the mapped vfs subtree

    HRESULT MapArchive ( const wchar_t * name , const wchar_t * physicalPath , IMGDFReadOnlyFile * parent , IMGDFReadOnlyVirtualFileSystem * vfs , IMGDFReadOnlyFile ** root )
    Parameters
    name The name of the archive
    physicalPath The physical path on disk containing the archive
    parent The VFS parent node of the archive
    vfs The VFS the archive will belong to
    root Pointer to the root node of the mapped vfs subtree
    Returns
    S_OK if the archive could be mapped correctly, otherwise E_FAIL

  • IsArchive Whether this file/directory is recognised as an archive type

    BOOL IsArchive ( const wchar_t * physicalPath )
    Parameters
    physicalPath The physical path on disk of a possible achive file
    Returns
    True if the file is a recognized archive file to be handled by this handler

IMGDFCommonHost Provides an entrypoint for a module to interact with the MGDF host. Methods in this interface are safe to be used from any thread

Inherits from: IMGDFLogger

  • FatalError This method should be invoked when a fatal error is encountered

    void FatalError ( const small * sender , const small * message )
    Parameters
    sender The location or component the error occurred in
    message Details of the fatal error

  • GetRenderSettings Get the render settings manager

    void GetRenderSettings ( IMGDFRenderSettingsManager ** settings )
    Parameters
    settings The render settings manager

  • GetTimer Get the host timer

    void GetTimer ( IMGDFTimer ** timer )
    Parameters
    timer Pointer to the host timer

  • GetMGDFVersion Gets the current version of the framework

    const MGDFVersion * GetMGDFVersion ( )
    Returns
    The current version of the framework

  • GetVFS Get the readonly content filesystem

    void GetVFS ( IMGDFReadOnlyVirtualFileSystem ** vfs )
    Parameters
    vfs The readonly filesystem

  • GetWorkingVFS Get the read/write working folder

    void GetWorkingVFS ( IMGDFWriteableVirtualFileSystem ** vfs )
    Parameters
    vfs The writeable filesystem

  • GetD3DDevice Get the direct3d device object from the host

    void GetD3DDevice ( ID3D11Device ** device )
    Parameters
    device The direct3d device object from the host

  • GetD2DDevice Get the direct2d device object from the host

    void GetD2DDevice ( ID2D1Device ** device )
    Parameters
    device The direct2d device object from the host

  • GetDebug Get the onscreen debug overlay interface

    void GetDebug ( IMGDFDebug ** debug )
    Parameters
    debug Pointer to a debug overlay object

  • CreateCPUCounter Create a performance counter for profiling CPU time taken. When no longer used it should be released

    HRESULT CreateCPUCounter ( IMGDFMetric * metric , IMGDFPerformanceCounter ** counter )
    Parameters
    metric The metric the counter should update
    counter Points to the created counter
    Returns
    S_OK if the counter could be created, otherwise an error code is returned

  • CreateCounterMetric Create or get an existing metric for a monotonically increasing counter

    HRESULT CreateCounterMetric ( const small * name , const small * description , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • CreateGaugeMetric Create or get an existing metric that can go up and down over time

    HRESULT CreateGaugeMetric ( const small * name , const small * description , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • CreateHistogramMetric Create or get an existing metric that can go up and down over time

    HRESULT CreateHistogramMetric ( const small * name , const small * description , const double * buckets , const UINT64 bucketCount , IMGDFMetric ** metric )
    Parameters
    name The name of the metric
    description A description of what the metric is measuring
    buckets Pointer to an array of buckets used in the histogram
    bucketCount The length of the buckets array parameter
    metric Points to the created metric
    Returns
    S_OK if the metric could be created, otherwise an error code is returned

  • QueueDeviceReset After a module receives an RTOnBeforeDeviceReset callback, calling this tells the host that all references to the previous D3D device have been cleaned up and that the device can be safely reset

    void QueueDeviceReset ( )

IMGDFDebug Controls the data displayed in the MGDF debug overlay sheet (press ALT-F12 to see in game)

Inherits from: IUnknown

  • Set Set some data to display in the overlay

    void Set ( const small * section , const small * key , const small * value )
    Parameters
    section The section to display the key:value in
    key The key to display
    value The value to display

  • Clear Clear some data out of the overlay

    void Clear ( const small * section , const small * key )
    Parameters
    section To clear the key from
    key The key to clear (if null, clears all keys in the section)

  • IsShown Whether the debug overlay is currently visible

    BOOL IsShown ( )
    Returns
    Whether the debug overlay is currently visible

  • ToggleShown Toggle the visibility status of the overlay

    void ToggleShown ( )

IMGDFFile Provides a base interface for filesystem access that is common across the readonly virtual filesystem and writeable save and working directories.

Inherits from: IUnknown

  • GetChildCount Get how many children this file has

    UINT64 GetChildCount ( )
    Returns
    How many children this file has

  • IsFolder Determines if the file entity is a folder

    BOOL IsFolder ( )
    Returns
    True if the file is a folder

  • IsOpen Determines if the file has an open reader

    BOOL IsOpen ( )
    Returns
    True if the file has an open reader

  • Open Attempt to open the file for reading. Only one fileReader can be open for a file at any time. Because of this, you should ensure that any reader is closed after it is no longer needed.

    HRESULT Open ( IMGDFFileReader ** reader )
    Parameters
    reader Pointer to any reader that is created
    Returns
    S_OK if the reader was created, E_FAIL if the file could not be opened or E_ACCESSDENIED if it was already open

  • GetLastWriteTime Find the last write time of the file

    UINT64 GetLastWriteTime ( )
    Returns
    A timestamp indicating the last write time

  • GetPhysicalName Gets the physical name of this file on disk

    HRESULT GetPhysicalName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

  • GetPhysicalPath Gets the physical path to this file

    HRESULT GetPhysicalPath ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file path
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

  • GetLogicalName Gets the logical name of this file

    HRESULT GetLogicalName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

  • GetLogicalPath Gets the logical path to this file

    HRESULT GetLogicalPath ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the file name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

IMGDFFileReader Provides an interface for reading data from a file

Inherits from: IUnknown

  • Read Reads the specified number of bytes into the buffer

    UINT32 Read ( void * buffer , UINT32 length )
    Parameters
    buffer A buffer to store the read data
    length The max amount of data that can be read into the buffer
    Returns
    The amount of bytes actually read into the buffer

  • SetPosition Sets the read position of the file in bytes

    void SetPosition ( INT64 pos )
    Parameters
    pos The read position of the file in bytes

  • GetPosition Get the current read position of the file in bytes

    INT64 GetPosition ( )
    Returns
    The read position in the file

  • EndOfFile Determines whether the file read position has reached the end of the file

    BOOL EndOfFile ( )
    Returns
    True if the read position is past the end of the file

  • GetSize Get the size of the file in bytes

    INT64 GetSize ( )
    Returns
    The filesize in bytes (for compressed archives this value is the uncompressed size)

IMGDFFileWriter Provides an interface for writing data to a file

Inherits from: IUnknown

  • Write Writes the specified number of bytes into the buffer

    UINT32 Write ( void * buffer , UINT32 length )
    Parameters
    buffer A buffer to store the write data
    length The max amount of data to write to the file
    Returns
    The amount of bytes actually written to the file

  • SetPosition Sets the write position of the file in bytes

    void SetPosition ( INT64 pos )
    Parameters
    pos The write position of the file in bytes

  • GetPosition Get the current write position of the file in bytes

    INT64 GetPosition ( )
    Returns
    The write position in the file

IMGDFGame Provides information regarding the current game being run and the preferences associated with that game

Inherits from: IUnknown

  • GetName Get the name of the current game running

    const small * GetName ( )
    Returns
    The name of the current game running

  • GetUid Get the uid of the current game running

    const small * GetUid ( )
    Returns
    The name of the current game running

  • GetVersion Get the version of the current game running

    void GetVersion ( MGDFVersion * version )
    Parameters
    version The version of the current game running

  • HasPreference Determine if the game has a preference for the given key

    BOOL HasPreference ( const small * name )
    Parameters
    name The preference name
    Returns
    True if the key has an associated value

  • GetPreference Determine if the game has a preference for the given key and return its value. Preferences can be defined in a games game.json file, or new ones can be added/overwritten by calling SetPreference

    HRESULT GetPreference ( const small * name , small * value , UINT64 * length )
    Parameters
    name The preference name
    value Buffer to store the value associated with the key or nullptr if there is no such key
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the value was found and the buffer was the correct length otherwise E_FAIL

  • SetPreference Change the value of a preference

    void SetPreference ( const small * name , const small * value )
    Parameters
    name The preference name
    value The new preference value

  • SetPreferences Sets a number of preferences in one go. Used for applying system render & sound settings

    void SetPreferences ( IMGDFPreferenceSet * preferences )
    Parameters
    preferences A set of preferences

  • SavePreferences Save the current preferences list

    void SavePreferences ( )

  • ResetPreferences Reload all preferences to their user independent default values

    void ResetPreferences ( )

IMGDFGamepad Provides the ability to query the state of and control other properties of an XInput compatible gamepad connected to the PC

Inherits from: IUnknown

  • IsConnected Determines if a controller is connected

    BOOL IsConnected ( )
    Returns
    True if if a controller is connected

  • IsButtonDown Determines if a button is pressed

    BOOL IsButtonDown ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button is being held down

  • IsButtonUp Determines if a button is NOT pressed

    BOOL IsButtonUp ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button is not being pressed

  • IsButtonPress Determines if a button press has occured

    BOOL IsButtonPress ( MGDFGamepadButton button )
    Parameters
    button The gamepad button code representing the desired button
    Returns
    True if the button has been pressed (i.e pressed down then released)

  • GetLeftTrigger Returns the state of the controllers left trigger

    UINT8 GetLeftTrigger ( )
    Returns
    0 for idle to 255 for fully held

  • GetRightTrigger Returns the state of the controllers right trigger

    UINT8 GetRightTrigger ( )
    Returns
    0 for idle to 255 for fully held

  • GetLeftThumbX Returns the state of the left thumbstick on the X axis

    INT32 GetLeftThumbX ( )
    Returns
    -32768 for far left to +32767 for far right

  • GetLeftThumbY Returns the state of the left thumbstick on the Y axis

    INT32 GetLeftThumbY ( )
    Returns
    -32768 for top to +32767 for bottom

  • GetRightThumbX Returns the state of the right thumbstick on the X axis

    INT32 GetRightThumbX ( )
    Returns
    -32768 for far left to +32767 for far right

  • GetRightThumbY Returns the state of the right thumbstick on the Y axis

    INT32 GetRightThumbY ( )
    Returns
    -32768 for top to +32767 for bottom

  • SetVibrationSpeed Sets the vibration intensity in the left and right vibrator motors of the controller, valid values are 0-65535

    void SetVibrationSpeed ( UINT16 left , UINT16 right )
    Parameters
    left The intensity of the left vibrator motor
    right The intensity of the right vibrator motor

IMGDFGameState A saved game state and its associated metadata

Inherits from: IUnknown

  • GetMetadata Gets the value of a metadata key

    HRESULT GetMetadata ( const small * key , small * value , UINT64 * length )
    Parameters
    key The name of the metadata key
    value Buffer to store the value associated with the key or nullptr if there is no such key
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the value was found and the buffer was the correct length otherwise E_FAIL

  • SetMetadata Sets the value of a metadata key

    HRESULT SetMetadata ( const small * key , const small * value )
    Parameters
    key The name of the metadata key
    value The value associated with the key
    Returns
    S_OK if the value could be stored

  • IsNew Is this a new game state with no persisted data that has been created from a recent call to CreateGameState

    BOOL IsNew ( )
    Returns
    True if the game state is new with no persisted data

  • GetVersion Get the version of the Module that saved this game state

    void GetVersion ( MGDFVersion * version )
    Parameters
    version The version of the Module that saved this game state

  • GetVFS Get the readonly virtual filesystem for the game states previously persisted data.

    HRESULT GetVFS ( IMGDFReadOnlyVirtualFileSystem ** vfs )
    Parameters
    vfs The virtual filesystem for accessing the game states data
    Returns
    S_OK if the virtual filesystem could be mounted, will fail if the game state is new

  • BeginSave Begins the process of saving the gamestate data. Once finished saving all data to the VFS instance returned. Modules should release the VFS to commit the save

    HRESULT BeginSave ( IMGDFWriteableVirtualFileSystem ** pending )
    Parameters
    pending A VFS mounted in a temporary save directory, once released any data in this directory will be copied into the permanent game state data directory
    Returns
    S_OK if the VFS could be mounted

IMGDFInputManager Provides a means for modules to access information regarding user input from the mouse, keyboard, and xinput controllers

Inherits from: IUnknown

  • ShowCursor Determines whether the OS cursor is displayed or not

    void ShowCursor ( BOOL show )
    Parameters
    show Whether to show the cursor or not

  • IsKeyDown Determines if a key is presed

    BOOL IsKeyDown ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key is being held down

  • IsKeyUp Determines if a key is NOT pressed

    BOOL IsKeyUp ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key is not being pressed

  • IsKeyPress Determines if a keypress has occured

    BOOL IsKeyPress ( UINT16 key )
    Parameters
    key The Microsoft Virtual key code representing the desired key (see here for a list http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)
    Returns
    True if the key has been pressed (i.e pressed down then released)

  • GetMouseX Get the x position of the mouse

    INT32 GetMouseX ( )
    Returns
    The x position of the mouse relative to the left of the screen in pixels

  • GetMouseY Get the y position of the mouse

    INT32 GetMouseY ( )
    Returns
    The y position of the mouse relative to the top of the screen in pixels

  • GetMouseDX Get the x movement of the mouse in the current frame

    INT32 GetMouseDX ( )
    Returns
    The x movement of the mouse in the current frame

  • GetMouseDY Get the y movement of the mouse in the current frame

    INT32 GetMouseDY ( )
    Returns
    The y movement of the mouse in the current frame

  • GetMouseDZ Get the position of the scroll wheel

    short GetMouseDZ ( )
    Returns
    The change in position of the scroll wheel, this value will increment/decrement in divisions of 120 depending on direction

  • IsButtonDown Determine if a mouse button is down

    BOOL IsButtonDown ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button is held down

  • IsButtonUp Determine if a mouse button is up

    BOOL IsButtonUp ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button is NOT held down

  • IsButtonClicked Determine if a mouse button was clicked

    BOOL IsButtonClicked ( MGDFMouse mouseButton )
    Parameters
    mouseButton The mousebutton code representing the desired button
    Returns
    True if the button has been clicked, i.e held down then released

  • GetGamepadCount Get the maximum number of gamepads available (not all of them may be connected)

    UINT64 GetGamepadCount ( )
    Returns
    The maximum number of gamepads available (not all of them may be connected)

  • GetGamepads Gets a list of all compatible gamepads connected to the PC

    void GetGamepads ( IMGDFGamepad ** gamepads )
    Parameters
    gamepads Pointer to an array of gamepads (must be large enough to fit GetGamepadCount entries)

IMGDFLogger The MGDF logging system

Inherits from: IUnknown

  • SetLoggingLevel Set the current logging verbosity level

    void SetLoggingLevel ( MGDFLogLevel level )
    Parameters
    level The verbosity level

  • GetLoggingLevel Get the current logging verbosity level

    MGDFLogLevel GetLoggingLevel ( )
    Returns
    The current logging verbosity level

  • Log Write an entry to the log

    void Log ( const small * sender , const small * message , MGDFLogLevel level )
    Parameters
    sender The location or component writing the log message
    message The content of the log message
    level The verbosity filter for writing out the message. The message will be written if this is less than or equal to the current logging level

IMGDFMetric Allows recording of a metric value over time. These can then be exposed via the Prometheus metrics server endpoint when enabled

Inherits from: IUnknown

  • Record Records the latest value of the metric

    void Record ( double value , const MGDFTags * tags )
    Parameters
    value The latest value of the metric
    tags Any tags to identify with this recording of the metric, pass NULL if no tags are to be included

IMGDFModule The interface to be implemented by an MGDF game

Inherits from: IUnknown

  • STNew Called by the host after a module is first created and should be used to do perform any initialization required by the module

    BOOL STNew ( IMGDFSimHost * host )
    Parameters
    host The simulation thread host
    Returns
    False if the module experiences a fatal error on initialization

  • STUpdate Called once per simulation timestep by the host once the game is running and represents the main sim loop

    BOOL STUpdate ( IMGDFSimHost * host , double elapsedTime )
    Parameters
    host The simulation thread host
    elapsedTime The simulation timestep
    Returns
    False if the module experiences a fatal error updating the scene

  • STShutDown Called by the host to tell the module to cleanup and shutdown as soon as possible. This is invoked when external events such as clicking the windows close button try to close the application. After being invoked it is the modules responsibility to call the ->Shutdown() function as soon as possible in order to actually terminate the application. This function may be called multiple times.

    void STShutDown ( IMGDFSimHost * host )
    Parameters
    host The simulation thread host

  • RTBeforeFirstDraw Called by the host immediately before the first call to RTDrawScene

    BOOL RTBeforeFirstDraw ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTDraw Called by the host once per render frame. The module should do any rendering required for the current frame in here

    BOOL RTDraw ( IMGDFRenderHost * host , double alpha )
    Parameters
    host The render thread host
    alpha How far between the current and next simulation frame (0-1)
    Returns
    False if the module experiences a fatal error drawing the scene

  • RTBeforeBackBufferChange Called by the host if the swap chain options need to be changed, or the display window needs to be resized. The module should clear out all references to the previous back buffer so a new resized backbuffer can be set

    BOOL RTBeforeBackBufferChange ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTBackBufferChange Called by the host after the swap chain options has been changed, or the display window has been resized. The module should re-acquire references to the new backbuffer or resize any backbuffer size dependent resources u

    BOOL RTBackBufferChange ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTBeforeDeviceReset Called by the host if the dxgi device needs to be removed. The module should clean out all device dependent resources and references to the old d3d device, which will now be invalid.

    BOOL RTBeforeDeviceReset ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • RTDeviceReset Called by the host after the dxgi device has been reset, the module should recreate any device dependent resources that were removed in RTBeforeDeviceReset

    BOOL RTDeviceReset ( IMGDFRenderHost * host )
    Parameters
    host The render thread host
    Returns
    False if the module experiences a fatal error

  • Panic Called by the host when a fatalError event occurs. This method gives the module a chance to clean up any memory/open files etc. as best it can before the host aborts. Methods on the render and sim hosts should not be accessed from within this method

    void Panic ( )

IMGDFPerformanceCounter A names performance counter that can be used to time the duration of events. The results of these counters are shown in the MGDF debug overlay (press ALT-F12 to see in game)

Inherits from: IUnknown

  • GetMetric Gets the metric the counter updates

    void GetMetric ( IMGDFMetric ** metric )
    Parameters
    metric The metric the counter updates

  • Begin Begin timing by creating a performance counter scope. The timing is recorded at the point the scope is released

    HRESULT Begin ( const MGDFTags * tags , IMGDFPerformanceCounterScope ** scope )
    Parameters
    tags Any tags to identify with this counter, pass NULL if no tags are to be included
    scope Points to the performance counter scope created
    Returns
    S_OK if the the performance counter scope was created, otherwise will return an error code

  • GetAverageValue Get the average value recorded by this timer

    double GetAverageValue ( )
    Returns
    The average value recorded by the timer

IMGDFPerformanceCounterScope Tracks an interval of time being recorded by a performance counter. When released the timing recorded will be the duration of time between the scopes creation and release

Inherits from: IUnknown

IMGDFPreferenceSet A set of preferences that can be persisted

Inherits from: IUnknown

IMGDFReadOnlyFile Provides an interface for navigating a readonly file/directory structure in the virtual filesystem. Directories have no data but can have subfiles Files have no subfiles (except for archives) but may have data. Archives that have been added to the vfs are mapped as files with the same name as the archive filename, but unlike normal files they also have a tree of subdirectories containing the uncompressed archive data

Inherits from: IMGDFFile

  • GetParent Gets the parent of this file. If this file is the root of the virtual filesystem, then this will be nullptr

    BOOL GetParent ( IMGDFReadOnlyFile ** parent )
    Parameters
    parent Pointer to the parent of this file.
    Returns
    If this file is the root of the filesystem, then return false

  • GetChild Gets a child of this file with the given name (if any)

    BOOL GetChild ( const wchar_t * name , IMGDFReadOnlyFile ** child )
    Parameters
    name The child name of this file
    child The child file of the current file. If no such file exists, nullptr is returned
    Returns
    True if the child could be found

  • GetAllChildren Get all the children of this file (non-recursive)

    void GetAllChildren ( IMGDFReadOnlyFile ** childBuffer )
    Parameters
    childBuffer An array to store the results (must be large enough to hold GetChildCount entries)

  • IsArchive Determines if the file is a (or is a member of) an archive file

    BOOL IsArchive ( )
    Returns
    True if the file is a (or is a member of) an archive file

  • GetVFS Get the virtual filesystem this file belongs to

    void GetVFS ( IMGDFReadOnlyVirtualFileSystem ** vfs )
    Parameters
    vfs The virtual filesystem this file belongs to

  • CopyTo Copies this file or folder to the desired writeable target location

    HRESULT CopyTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be copied, otherwise E_FAIL

IMGDFReadOnlyVirtualFileSystem Provides an interface for accessing the readonly filesystem, which is a fast read only interface to access game content files. The root MGDF filesystem is mounted from the game/content folder.

Inherits from: IUnknown

  • GetFile Get the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive. The /game/content folder in the MGDF install root folder is mounted as the root of the logical filesystem, and no access outside of this folder is permitted.

    BOOL GetFile ( const wchar_t * logicalPath , IMGDFReadOnlyFile ** file )
    Parameters
    logicalPath The vfs path to the file
    file Pointer to the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive
    Returns
    True if the file could be found

  • GetRoot Get the root node of the filesystem. In the physical filesystem this corresponds to the /game/content folder.

    void GetRoot ( IMGDFReadOnlyFile ** root )
    Parameters
    root Pointer to the root node of the filesystem

  • GetLogicalPath Get the logical path to a file

    HRESULT GetLogicalPath ( IMGDFReadOnlyFile * file , wchar_t * path , UINT64 * length )
    Parameters
    file The file to get the logical path to
    path Buffer to store the logical path
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

IMGDFRenderHost Provides an entrypoint for a module to interact with the MGDF host. This interface inherits from ICommonHost and provides additional methods which are safe to be used ONLY from the render thread.

Inherits from: IMGDFCommonHost

  • SetBackBufferRenderTarget Set the current back buffer as the render target for the specified d2d device context

    BOOL SetBackBufferRenderTarget ( ID2D1DeviceContext * context )
    Parameters
    context The d2d device context to set the render target for
    Returns
    True if the back buffer can be set as the render target for the device context

  • GetBackBuffer Gets the current back buffer texture.

    void GetBackBuffer ( ID3D11Texture2D ** backbuffer )
    Parameters
    backbuffer The current back buffer texture. The pointer returned by this method becomes invalid when the modules OnReset event is fired

  • GetDepthStencilBuffer Gets the current depth stencil buffer texture.

    void GetDepthStencilBuffer ( ID3D11Texture2D ** stencilBuffer )
    Parameters
    stencilBuffer The current stencil buffer texture. The pointer returned by this method becomes invalid when the modules OnReset event is fired

  • GetBackBufferDescription Gets the description of the backbuffer and depthStencilBuffer textures.

    void GetBackBufferDescription ( D3D11_TEXTURE2D_DESC * backBufferDesc , D3D11_TEXTURE2D_DESC * depthStencilBufferDesc )
    Parameters
    backBufferDesc The backbuffer description to populate. If null is passed, this field is not populated
    depthStencilBufferDesc The backbuffer description to populate. If null is passed, this field is not populated

  • CreateGPUCounter Create a performance counter for profiling GPU time taken in DirectX API calls. When no longer used it should be Released

    HRESULT CreateGPUCounter ( IMGDFMetric * metric , ID3D11DeviceContext * context , IMGDFPerformanceCounter ** counter )
    Parameters
    metric The metric the counter should update
    context The device context this counter measures
    counter Points to the created counter
    Returns
    E_FAIL if GPU counters are unsupported (using D3D_FEATURE_LEVEL_9_3 or less) otherwise returns S_OK

IMGDFRenderSettingsManager Provides an interface for getting and setting the hosts various display settings

Inherits from: IUnknown

  • GetMaxFrameLatency Gets the number of frames that the swap chain is allowed to queue for rendering.

    UINT32 GetMaxFrameLatency ( )
    Returns
    True if vsync is enabled

  • SetMaxFrameLatency Gets the number of frames that the swap chain is allowed to queue for rendering.

    void SetMaxFrameLatency ( UINT32 frames )
    Parameters
    frames The maximum number of frames that can be queued (1+)

  • GetVSync Gets the current vsync setting

    BOOL GetVSync ( )
    Returns
    True if vsync is enabled

  • SetVSync Sets the current vsync setting

    void SetVSync ( BOOL vsync )
    Parameters
    vsync True if vsync is to be enabled

  • GetFullscreen Gets the current fullscreen setting

    void GetFullscreen ( MGDFFullScreenDesc * fullscreen )
    Parameters
    fullscreen A description of the current fullscreen settings

  • SetFullscreen Sets the current fullscreen setting

    void SetFullscreen ( const MGDFFullScreenDesc * fullscreen )
    Parameters
    fullscreen A description of the desired fullscreen settings

  • GetMultiSampleLevelCount Get the number of supported multisample levels

    UINT64 GetMultiSampleLevelCount ( )
    Returns
    The number of supported multisample levels

  • GetMultiSampleLevel Get the available multisample level supported by the display adaptor at the given index ( 0 to GetMultiSampleLevelCount() - 1 )

    BOOL GetMultiSampleLevel ( UINT64 index , UINT32 * level )
    Parameters
    index The multisample index
    level Returns the multisample level at the given index
    Returns
    True if a supported multisample level is present at the given index, false otherwise.

  • SetBackBufferMultiSampleLevel Set the display adaptors current multisample level, this changed setting is not applied until ApplySettings is called.

    BOOL SetBackBufferMultiSampleLevel ( UINT32 multisampleLevel )
    Parameters
    multisampleLevel The desired multisample level for the backbuffer
    Returns
    Returns false if the desired multisample level cannot be set.

  • GetBackBufferMultiSampleLevel Get the current multisample level in use by the adaptor

    UINT32 GetBackBufferMultiSampleLevel ( )
    Returns
    The current multisample level in use by the adaptor

  • SetCurrentMultiSampleLevel Set the desired multisample level for off screen render targets. This setting is not used directly by the framework but any client code should query this property when creating render targets that may require multisampling (see also GetCurrentMultiSampleLevel() )

    BOOL SetCurrentMultiSampleLevel ( UINT32 multisampleLevel )
    Parameters
    multisampleLevel The desired multisample level for off screen render targets
    Returns
    Returns false if the desired multisample level cannot be set.

  • GetCurrentMultiSampleLevel Get the current desired multisample level for off screen render targets

    UINT32 GetCurrentMultiSampleLevel ( UINT32 * quality )
    Parameters
    quality If specified this parameter will be initialized with the maximum multisampling quality setting for the current multisample level
    Returns
    The current desired multisample level for off screen render targets

  • GetAdaptorModeCount Get the number of supported adaptor modes

    UINT64 GetAdaptorModeCount ( )
    Returns
    The number of supported adaptor modes

  • GetAdaptorMode Get a supported adaptor mode at the given index (0 to GetAdaptorModeCount - 1)

    BOOL GetAdaptorMode ( UINT64 index , MGDFAdaptorMode * mode )
    Parameters
    index The adaptor mode index
    mode Will be set to the the adaptor mode at the given index
    Returns
    True if an adaptor mode exists at a particular index

  • GetAdaptorModeFromDimensions Get the adaptor mode (if any) matching the requested width and height, if no matching adaptor is found, false is returned

    BOOL GetAdaptorModeFromDimensions ( UINT32 width , UINT32 height , MGDFAdaptorMode * mode )
    Parameters
    width The desired width of the adaptor mode
    height The desired height of the adaptor mode
    mode Will be set to the matching adaptor mode found (if any)
    Returns
    True if a supported adaptor mode exists for the given width and height

  • GetCurrentAdaptorMode Get the current adaptor mode being used when running in fullscreen mode

    MGDFAdaptorMode * GetCurrentAdaptorMode ( MGDFAdaptorMode * mode )
    Parameters
    mode Will be set to the current adaptor mode being used.
    Returns
    The current adaptor mode being used (a pointer to mode)

  • SetCurrentAdaptorMode Sets the current display adaptor mode when running in fullscreen mode, this changed setting is not applied until ApplyChanges is called.

    BOOL SetCurrentAdaptorMode ( const MGDFAdaptorMode * mode )
    Parameters
    mode The adaptor mode to use
    Returns
    True if the adaptor mode is supported and can be applied, false otherwise

  • SetCurrentAdaptorModeToNative Sets the current display adaptor mode when running in fullscreen mode to the screens native fullscreen resolution.

    BOOL SetCurrentAdaptorModeToNative ( MGDFAdaptorMode * mode )
    Parameters
    mode The adaptor that was chosen
    Returns
    True if the adaptor mode could be changed, false otherwise

  • SetWindowSize Sets the size of the window when running in windowed mode. While running in fullscreen, this function has no effect.

    void SetWindowSize ( UINT32 width , UINT32 height )
    Parameters
    width The width of the window
    height The height of the window

  • GetScreenX Get the current screen width, based on the current adaptor mode in fullscreen, or on the window dimensions otherwise

    UINT32 GetScreenX ( )
    Returns
    The current screen width

  • GetScreenY Get the current screen height, based on the current adaptor mode in fullscreen, or on the window dimensions otherwise

    UINT32 GetScreenY ( )
    Returns
    Thr current screen height

  • ApplySettings Queues the swap chain to be reset on the beginning of the next frame. This applies any render settings

    void ApplySettings ( )

  • GetPreferences Gets the current persistable render settings.

    void GetPreferences ( IMGDFPreferenceSet ** preferences )
    Parameters
    preferences A pointer to a preference set that can be passed into the IMGDFGame SetPreferences method to set the preferences

IMGDFSaveManager An interface to control saving/loading gamestate data

Inherits from: IUnknown

  • GetSaveCount Get the number of saved gamestates available

    UINT64 GetSaveCount ( )
    Returns
    The number of saved gamestates available

  • GetSave Get the saved state at the given index.

    HRESULT GetSave ( UINT64 index , IMGDFGameState ** save )
    Parameters
    index Which gamestate, valid values are 0 to GetSaveCount - 1.
    save Pointer to the gamestate at the given index
    Returns
    S_OK if a valid gamestate exists at the given index, otherwise an error code is returned

  • DeleteSave Deletes a saved gamestate

    HRESULT DeleteSave ( IMGDFGameState * state )
    Parameters
    state A gamestate previously returned from GetSave
    Returns
    S_OK if the gamestate could be deleted, otherwise an error code is returned

  • CreateGameState Creates a new empty gamestate without metadata or any persisted data

    void CreateGameState ( IMGDFGameState ** save )
    Parameters
    save A pointer to the created gamestate.

IMGDFSimHost Provides an entrypoint for a module to interact with the MGDF host. This interface inherits from IMGDFCommonHost and provides additional methods which are safe to be used ONLY from the sim thread.

Inherits from: IMGDFCommonHost

  • GetSaves Gets the save manager

    void GetSaves ( IMGDFSaveManager ** save )
    Parameters
    save The save manager object

  • GetGame Get information regarding the current game and its preferences

    void GetGame ( IMGDFGame ** game )
    Parameters
    game Pointer to object containing information regarding the game and its preferences

  • GetSound Get the sound manager

    void GetSound ( IMGDFSoundManager ** sound )
    Parameters
    sound The sound manager, nullptr if the audio subsystem failed to initialize

  • GetStatistics Get the statistics manager

    void GetStatistics ( IMGDFStatisticsManager ** statistics )
    Parameters
    statistics The statistics manager

  • GetInput Get the input manager

    void GetInput ( IMGDFInputManager ** input )
    Parameters
    input Pointer to an input manager

  • ShutDown Tells the host to shut down the game immediately

    void ShutDown ( )

  • QueueShutDown Tells the host to invoke the modules shutdown callback

    void QueueShutDown ( )

IMGDFSound An sound source in 3d space

Inherits from: IUnknown

  • GetName The name of the sound

    HRESULT GetName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the sound name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

  • GetPosition The position of the sound

    MGDFSoundPosition * GetPosition ( MGDFSoundPosition * position )
    Parameters
    position The position of the sound
    Returns
    The position of the sound

  • GetVelocity The velocity of the sound

    MGDFSoundPosition * GetVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the sound
    Returns
    The velocity of the sound

  • SetPosition Set the position of the sound

    MGDFSoundPosition * SetPosition ( MGDFSoundPosition * position )
    Parameters
    position The position of the sound
    Returns
    The position of the sound

  • SetVelocity Set the velocity of the sound

    MGDFSoundPosition * SetVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the sound
    Returns
    The velocity of the sound

  • GetInnerRange The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

    float GetInnerRange ( )
    Returns
    The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

  • SetInnerRange Set The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

    void SetInnerRange ( float innerRange )
    Parameters
    innerRange The distance (from the observer) at which the sound intensity reaches its maximum. Getting closer than this will not cause the sound intensity to get any greater

  • GetOuterRange The distance (from the observer) at which the sound intensity reaches 0

    float GetOuterRange ( )
    Returns
    The distance (from the observer) at which the sound intensity reaches its 0

  • SetOuterRange Set The distance (from the observer) at which the sound intensity reaches 0

    void SetOuterRange ( float outerRange )
    Parameters
    outerRange The distance (from the observer) at which the sound intensity reaches 0

  • GetSourceRelative Does the sound stay relative to the listeners position or is it fixed in absolute space

    BOOL GetSourceRelative ( )
    Returns
    True if the sound is always relative to the listeners position

  • SetSourceRelative Does the sound stay relative to the listeners position or is it fixed in absolute space

    void SetSourceRelative ( BOOL sourceRelative )
    Parameters
    sourceRelative True if the sound is always relative to the listeners position

  • GetVolume Get the current volume of the sound (ignoring attenuation due to position)

    float GetVolume ( )
    Returns
    The current volume of the sound (ignoring attenuation due to position)

  • SetVolume Set the current volume of the sound (ignoring attenuation due to position)

    void SetVolume ( float volume )
    Parameters
    volume The current volume of the sound (ignoring attenuation due to position)

  • GetPitch Get the pitch of the current sound

    float GetPitch ( )
    Returns
    1.0 if the pitch is unchanged. between 0.5 and 1.0 is lower, and between 1.0 and 2.0 is higher pitched

  • SetPitch Set the pitch of the current sound

    void SetPitch ( float pitch )
    Parameters
    pitch 1.0 if the pitch is unchanged. between 0.5 and 1.0 is lower, and between 1.0 and 2.0 is higher pitched

  • SetPriority Set the priority used by the sound system to determine which sounds get deactivated if not enough sound sources are available to play all sounds

    void SetPriority ( INT32 priority )
    Parameters
    priority The priority to use for the sound. Higher values mean higher priority

  • GetPriority Get the priority used by the sound system to determine which sounds get deactivated if not enough sound sources are available to play all sounds

    INT32 GetPriority ( )
    Returns
    Priority the priority to use for the sound. Higher values mean higher priority

  • GetLooping Get whether the sound will loop playback continously

    BOOL GetLooping ( )
    Returns
    True if the sound should loop continously

  • SetLooping Set whether the sound will loop playback continously

    void SetLooping ( BOOL looping )
    Parameters
    looping True if the sound should loop playback, false otherwise
    Returns
    Looping true if the sound should loop continously

  • Stop Stop the playing of the current playlist if it was playing or paused (resets playlist to the beginning aswell)

    void Stop ( )

  • Pause Pause the playing of the current playlist (if it was playing)

    void Pause ( )

  • Play Resume the playing of the current playlist (if it was paused or stopped)

    void Play ( )

  • IsStopped Determines if the playlist has stopped play

    BOOL IsStopped ( )
    Returns
    True if the playlist has stopped play

  • IsPaused Determines if the playlist has paused play

    BOOL IsPaused ( )
    Returns
    True if the playlist has paused play

  • IsPlaying Determines if the playlist is playing

    BOOL IsPlaying ( )
    Returns
    True if the playlist is playing

  • IsActive Is the sound currently playing or has it been culled

    BOOL IsActive ( )
    Returns
    True if the sound manager has culled this sound source

IMGDFSoundManager An interface for controlling positional sounds as well as streaming sound sources

Inherits from: IUnknown

  • GetListenerPosition Determine the position of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerPosition ( MGDFSoundPosition * listener )
    Parameters
    listener The position of the listener (i.e. the player)
    Returns
    The position of the listener (i.e. the player)

  • GetListenerVelocity Determine the velocity of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the listener (i.e. the player)
    Returns
    The velocity of the listener (i.e. the player)

  • GetListenerOrientationForward Get the vector representing the forward direction of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerOrientationForward ( MGDFSoundPosition * orientationForward )
    Parameters
    orientationForward The vector representing the forward direction of the listener
    Returns
    The vector representing the forward direction of the listener

  • GetListenerOrientationUp Get the vector representing the upward direction of the listener (i.e. the player)

    MGDFSoundPosition * GetListenerOrientationUp ( MGDFSoundPosition * orientationUp )
    Parameters
    orientationUp The vector representing the upward direction of the listener
    Returns
    The vector representing the upward direction of the listener

  • SetListenerPosition Set the position of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerPosition ( MGDFSoundPosition * listener )
    Parameters
    listener The position of the listener (i.e. the player)
    Returns
    The position of the listener (i.e. the player)

  • SetListenerVelocity Set the velocity of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerVelocity ( MGDFSoundPosition * velocity )
    Parameters
    velocity The velocity of the listener (i.e. the player)
    Returns
    The velocity of the listener (i.e. the player)

  • SetListenerOrientationForward Set the vector representing the forward direction of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerOrientationForward ( MGDFSoundPosition * orientationForward )
    Parameters
    orientationForward The vector representing the forward direction of the listener
    Returns
    The vector representing the forward direction of the listener

  • SetListenerOrientationUp Set the vector representing the upward direction of the listener (i.e. the player)

    MGDFSoundPosition * SetListenerOrientationUp ( MGDFSoundPosition * orientationUp )
    Parameters
    orientationUp The vector representing the upward direction of the listener
    Returns
    The vector representing the upward direction of the listener

  • GetSoundVolume Get the master volume (0-1) All sounds volumes are relative to this setting

    float GetSoundVolume ( )
    Returns
    The master volume

  • SetSoundVolume Set the master volume (0-1) All sounds volumes are relative to this setting

    void SetSoundVolume ( float volume )
    Parameters
    volume The master volume

  • GetStreamVolume Get the master volume for streamed sounds (0-1) All streams volumes are relative to this setting

    float GetStreamVolume ( )
    Returns
    The master stream volume

  • SetStreamVolume Set the master volume for streamed sounds (0-1) All streams volumes are relative to this setting

    void SetStreamVolume ( float volume )
    Parameters
    volume The master stream volume

  • GetEnableAttenuation Get whether sounds should attenuate with thier distance from the listener

    BOOL GetEnableAttenuation ( )
    Returns
    True if sounds should attenuate with thier distance from the listener

  • SetEnableAttenuation Set whether sounds should attenuate with thier distance from the listener

    void SetEnableAttenuation ( BOOL enableAttenuation )
    Parameters
    enableAttenuation True if sounds should attenuate with thier distance from the listener

  • GetDopplerShiftFactor Get whether sounds will doppler shift based on thier relative velocity to the listener

    float GetDopplerShiftFactor ( )
    Returns
    Whether sounds will doppler shift based on thier relative velocity to the listener

  • SetDopplerShiftFactor Set whether sounds will doppler shift based on thier relative velocity to the listener

    void SetDopplerShiftFactor ( float dopplerShiftFactor )
    Parameters
    dopplerShiftFactor True if sounds should doppler shift based on thier relative velocity to the listener

  • GetSpeedOfSound Get the speed of sound used to calculate doppler shifting of sounds

    float GetSpeedOfSound ( )
    Returns
    The speed of sound used to calculate doppler shifting of sounds

  • SetSpeedOfSound Set the speed of sound used to calculate doppler shifting of sounds

    void SetSpeedOfSound ( float speedOfSound )
    Parameters
    speedOfSound The speed of sound used to calculate doppler shifting of sounds

  • CreateSound Create a sound by loading a file in the VFS into memory. When no INT32er used it should be Released

    HRESULT CreateSound ( IMGDFReadOnlyFile * file , INT32 priority , IMGDFSound ** sound )
    Parameters
    file The data source for the sound
    priority The priority of the sound (used to determine what should play if no free audio sources are available
    sound If the sound is created successfully, this will point to the created sound
    Returns
    S_OK if the sound was created successfully, otherwise an error code will be returned

  • CreateSoundStream Create a sound stream from a file in the VFS. When no longer used it should be Released

    HRESULT CreateSoundStream ( IMGDFReadOnlyFile * file , IMGDFSoundStream ** stream )
    Parameters
    file The data source for the sound stream
    stream If the stream is created successfully, this will point to the created stream
    Returns
    S_OK if the stream was created successfully, otherwise an error code will be returned

  • GetPreferences Gets the current persistable sound settings. Note: this only consists of master volume settings. Other settings like attenuation & speedOfSound need to be reset on startup

    void GetPreferences ( IMGDFPreferenceSet ** preferences )
    Parameters
    preferences A pointer to a preference set that can be passed into the IMGDFGame setPreferences method to set the preferences

IMGDFSoundStream A vorbis sound stream

Inherits from: IUnknown

  • GetName The name of the sound stream

    HRESULT GetName ( wchar_t * name , UINT64 * length )
    Parameters
    name Buffer to store the sound stream name
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

  • GetVolume Get the volume level (0-1)

    float GetVolume ( )
    Returns
    The volume level (0-1)

  • SetVolume Set the volume level (0-1)

    void SetVolume ( float volume )
    Parameters
    volume The volume level to set

  • GetPosition The position of playback in the stream (0 -> GetLength)

    UINT32 GetPosition ( )
    Returns
    The position of playback in the stream

  • GetLength The total length of the stream

    UINT32 GetLength ( )
    Returns
    The total length of the stream

  • Stop Stop the playing of the current stream if it was playing or paused (resets it to the beginning aswell)

    void Stop ( )

  • Pause Pause the playing of the current stream (if it was playing)

    void Pause ( )

  • Play Resume the playing of the current playlist (if it was paused or stopped)

    HRESULT Play ( )
    Returns
    Success if the sound could resume playing, otherwise returns an error code.

  • IsStopped Determines if the stream has stopped play

    BOOL IsStopped ( )
    Returns
    True if the stream has stopped play

  • IsPaused Determines if the stream has paused play

    BOOL IsPaused ( )
    Returns
    True if the stream has paused play

  • IsPlaying Determines if the stream is playing

    BOOL IsPlaying ( )
    Returns
    True if the stream is playing

IMGDFStatisticsManager Provides an interface for pushing statistics to a remote endpoint during a game session.

Inherits from: IUnknown

  • PushString Pushes a statistic to the remote statistics service (if one is specified)

    void PushString ( const small * name , const small * value , const MGDFTags * tags )
    Parameters
    name The name of the statistic tracker key
    value The value of the statistic
    tags Any tags to pass with the statistic (null if none are to be included)

  • PushMetric Pushes a metrics current value to the remote statistics service (if one is specified)

    void PushMetric ( IMGDFMetric * metric )
    Parameters
    metric The metric to push, this will be passed to the statistics service as a name/value pair

IMGDFTimer Provides an interface to the hosts high resolution CPU timer

Inherits from: IUnknown

  • GetCurrentTimeTicks Get the current system time in ticks

    LARGE_INTEGER GetCurrentTimeTicks ( )
    Returns
    The current system time in ticks

  • GetTimerFrequency Get the current system timer frequency

    LARGE_INTEGER GetTimerFrequency ( )
    Returns
    The current system timer frequency

  • ConvertDifferenceToSeconds Convert two system tick times into a duration in seconds

    double ConvertDifferenceToSeconds ( LARGE_INTEGER newTime , LARGE_INTEGER oldTime )
    Parameters
    newTime The newer of the two times
    oldTime The older of the two times
    Returns
    The difference betweeen the two parameters converted into seconds

IMGDFWriteableFile Provides an interface for navigating a writeable file/directory structure. These include writeable folders such as the working directory and save game folders.

Inherits from: IMGDFFile

  • Exists Does the file/folder exist

    BOOL Exists ( )
    Returns
    True if the file/folder exists

  • GetParent Gets the parent of this file. If this file is the root of the virtual filesystem, then this will be nullptr

    BOOL GetParent ( IMGDFWriteableFile ** parent )
    Parameters
    parent Pointer to the parent of this file.
    Returns
    If this file is the root of the filesystem then return false, otherwise true.

  • GetChild Gets a child of this file with the given name (if any)

    HRESULT GetChild ( const wchar_t * name , IMGDFWriteableFile ** child )
    Parameters
    name The child name of this file
    child The child file of the current file
    Returns
    S_OK if the child file could be found, E_FAIL otherwise

  • GetAllChildren Get all the children of this file (non-recursive)

    HRESULT GetAllChildren ( IMGDFWriteableFile ** childBuffer )
    Parameters
    childBuffer An array to store the results (must be large enough to hold GetChildCount entries)
    Returns
    S_OK if all the children could be stored in the provided buffer

  • OpenWrite Attempt to open the file for writing if the path to this file doesn't exist it will be created

    HRESULT OpenWrite ( IMGDFFileWriter ** writer )
    Parameters
    writer Pointer to a writer instance to be created
    Returns
    S_OK if the writer could be created, otherwise E_FAIL or E_ACCESSDENIED

  • CreateFolder Creates this as a folder (and any necessary parent folders along the way)

    HRESULT CreateFolder ( )
    Returns
    S_OK if the folder could be created, otherwise E_FAIL

  • Delete Deletes this file or folder (and its descendants). Note the root of a VFS cannot be deleted and will fail if attempted

    HRESULT Delete ( )
    Returns
    S_OK if the file or folder could be deleted, otherwise E_FAIL

  • MoveTo Moves this file or folder to the desired target location

    HRESULT MoveTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be moved, otherwise E_FAIL

  • CopyTo Copies this file or folder to the desired target location

    HRESULT CopyTo ( IMGDFWriteableFile * destination )
    Parameters
    destination The target location for this file/folder. If the destination exists it should be deleted first or else this call will fail.
    Returns
    S_OK if the file/folder could be copied, otherwise E_FAIL

  • GetVFS Get the virtual filesystem this file belongs to

    void GetVFS ( IMGDFWriteableVirtualFileSystem ** vfs )
    Parameters
    vfs The virtual filesystem this file belongs to

IMGDFWriteableVirtualFileSystem Provides an interface for accessing the writable filesystem, which is used for save game folders and the working directory

Inherits from: IUnknown

  • GetFile Get the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive.

    BOOL GetFile ( const wchar_t * logicalPath , IMGDFWriteableFile ** file )
    Parameters
    logicalPath The vfs path to the file
    file Pointer to the file/folder/archive in the specified logical directory. paths are delimited using the / character and names are case sensitive
    Returns
    True if the file could be found

  • GetRoot Get the root node of the filesystem. In the physical filesystem this corresponds to the /game/content folder.

    void GetRoot ( IMGDFWriteableFile ** root )
    Parameters
    root Pointer to the root node of the filesystem

  • GetLogicalPath Get the logical path to a file

    HRESULT GetLogicalPath ( IMGDFWriteableFile * file , wchar_t * path , UINT64 * length )
    Parameters
    file The file to get the logical path to
    path Buffer to store the logical path
    length The length of the buffer provided to store the value above. Will be set to the length required
    Returns
    S_OK if the buffer was the correct length otherwise E_FAIL

Structs

MGDFAdaptorMode The display settings for a particular adaptor mode

  • Width

    UINT32 Width

  • Height

    UINT32 Height

  • RefreshRateNumerator

    UINT32 RefreshRateNumerator

  • RefreshRateDenominator

    UINT32 RefreshRateDenominator

MGDFFullScreenDesc The current fullscreen options

  • FullScreen

    BOOL FullScreen

  • ExclusiveMode

    BOOL ExclusiveMode

MGDFSoundPosition The position of a sound source in 3d space

  • x

    float x

  • y

    float y

  • z

    float z

MGDFTags Allows a metric to be tagged with a collection of name/value pairs

  • Names

    const small ** Names

  • Values

    const small ** Values

  • Count

    UINT64 Count

MGDFVersion Represents a version number

  • Major

    INT32 Major

  • Minor

    INT32 Minor

  • Build

    INT32 Build

  • Revision

    INT32 Revision

Enumerations

MGDFGamepadButton All the gamepad button types recognized by the input manager

Values
MGDF_GAMEPAD_DPAD_UP
MGDF_GAMEPAD_DPAD_DOWN
MGDF_GAMEPAD_DPAD_LEFT
MGDF_GAMEPAD_DPAD_RIGHT
MGDF_GAMEPAD_START
MGDF_GAMEPAD_BACK
MGDF_GAMEPAD_LEFT_THUMB
MGDF_GAMEPAD_RIGHT_THUMB
MGDF_GAMEPAD_LEFT_SHOULDER
MGDF_GAMEPAD_RIGHT_SHOULDER
MGDF_GAMEPAD_A
MGDF_GAMEPAD_B
MGDF_GAMEPAD_X
MGDF_GAMEPAD_Y

MGDFLogLevel The logging levels available, LOG_ERROR is of the highest importance with LOG_HIGH messages being of the least importance

Values
MGDF_LOG_ERROR
MGDF_LOG_LOW
MGDF_LOG_MEDIUM
MGDF_LOG_HIGH

MGDFMouse This is represents all the various mouse buttons that are recognized by the input manager

Values
MGDF_MOUSE_LEFT
MGDF_MOUSE_RIGHT
MGDF_MOUSE_MIDDLE