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)
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
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.
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
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
The game update manifest file is a json file whose url 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 framework will request the manifest using the updateservice url (and append the gameUid as a querystring parameter). the 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.
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.
Sample HTTP request to https://example.com/statistics (Note the statisticsservice url in game.json would be https://example.com/statistics in this case)
POST https://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"}]}
Sample HTTP response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 29 {"errors":[], "success":true}
The MGDF S3 crash reporting service works in two steps, first by calling the supportUrl endpoing with crash metadata (see below). The service should then respond with a presigned S3 URL that the framework will then issue an HTTP Put for to upload a crash report zip file into. In order to use this feature you must have an AWS account with an S3 bucket set up & have supportType set to "S3" in your game.json file. You will also need to implement a compatible web service that implements the contract shown below.
Sample HTTP request to https://example.com/crashes (Note the supportUrl url in game.json would be https://example.com/crashes in this case)
POST https://example.com/crashes HTTP/1.1 Content-Type: application/json; charset=utf-8 Host: example.com Content-Length: 146 {"detail": "Exception thrown", "gameUid":"blah", "gameVersion":"1.2.3.4", "frameworkVersion":"1.2.3.4"}
Sample HTTP response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 29 {"errors":[], "success":true, "uploadUrl":"https://s3.amazonaws.com/yourbucket/crash.zip"}
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.
UINT64
GetCompatibleFeatureLevels
(
D3D_FEATURE_LEVEL *
levels
,
UINT64 *
featureLevelSize
)
HRESULT
GetCustomArchiveHandlers
(
IMGDFArchiveHandler **
list
,
UINT64 *
length
,
IMGDFLogger *
logger
)
HRESULT
GetModule
(
IMGDFModule **
module
)
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.
HRESULT
MapArchive
(
const wchar_t *
name
,
const wchar_t *
physicalPath
,
IMGDFReadOnlyFile *
parent
,
IMGDFReadOnlyVirtualFileSystem *
vfs
,
IMGDFReadOnlyFile **
root
)
BOOL
IsArchive
(
const wchar_t *
physicalPath
)
void
FatalError
(
const small *
sender
,
const small *
message
)
void
GetRenderSettings
(
IMGDFRenderSettingsManager **
settings
)
void
GetTimer
(
IMGDFTimer **
timer
)
const MGDFVersion *
GetMGDFVersion
(
)
void
GetVFS
(
IMGDFReadOnlyVirtualFileSystem **
vfs
)
void
GetWorkingVFS
(
IMGDFWriteableVirtualFileSystem **
vfs
)
void
GetD3DDevice
(
ID3D11Device **
device
)
void
GetD2DDevice
(
ID2D1Device **
device
)
void
GetDebug
(
IMGDFDebug **
debug
)
HRESULT
CreateCPUCounter
(
IMGDFMetric *
metric
,
IMGDFPerformanceCounter **
counter
)
HRESULT
CreateCounterMetric
(
const small *
name
,
const small *
description
,
IMGDFMetric **
metric
)
HRESULT
CreateGaugeMetric
(
const small *
name
,
const small *
description
,
IMGDFMetric **
metric
)
HRESULT
CreateHistogramMetric
(
const small *
name
,
const small *
description
,
const double *
buckets
,
const UINT64
bucketCount
,
IMGDFMetric **
metric
)
void
QueueDeviceReset
(
)
void
Set
(
const small *
section
,
const small *
key
,
const small *
value
)
void
Clear
(
const small *
section
,
const small *
key
)
BOOL
IsShown
(
)
void
ToggleShown
(
)
UINT64
GetChildCount
(
)
BOOL
IsFolder
(
)
BOOL
IsOpen
(
)
HRESULT
Open
(
IMGDFFileReader **
reader
)
UINT64
GetLastWriteTime
(
)
HRESULT
GetPhysicalName
(
wchar_t *
name
,
UINT64 *
length
)
HRESULT
GetPhysicalPath
(
wchar_t *
name
,
UINT64 *
length
)
HRESULT
GetLogicalName
(
wchar_t *
name
,
UINT64 *
length
)
HRESULT
GetLogicalPath
(
wchar_t *
name
,
UINT64 *
length
)
UINT32
Read
(
void *
buffer
,
UINT32
length
)
void
SetPosition
(
INT64
pos
)
INT64
GetPosition
(
)
BOOL
EndOfFile
(
)
INT64
GetSize
(
)
UINT32
Write
(
void *
buffer
,
UINT32
length
)
void
SetPosition
(
INT64
pos
)
INT64
GetPosition
(
)
const small *
GetName
(
)
const small *
GetUid
(
)
void
GetVersion
(
MGDFVersion *
version
)
BOOL
HasPreference
(
const small *
name
)
HRESULT
GetPreference
(
const small *
name
,
small *
value
,
UINT64 *
length
)
void
SetPreference
(
const small *
name
,
const small *
value
)
void
SetPreferences
(
IMGDFPreferenceSet *
preferences
)
void
SavePreferences
(
)
void
ResetPreferences
(
)
BOOL
IsConnected
(
)
BOOL
IsButtonDown
(
MGDFGamepadButton
button
)
BOOL
IsButtonUp
(
MGDFGamepadButton
button
)
BOOL
IsButtonPress
(
MGDFGamepadButton
button
)
UINT8
GetLeftTrigger
(
)
UINT8
GetRightTrigger
(
)
INT32
GetLeftThumbX
(
)
INT32
GetLeftThumbY
(
)
INT32
GetRightThumbX
(
)
INT32
GetRightThumbY
(
)
void
SetVibrationSpeed
(
UINT16
left
,
UINT16
right
)
HRESULT
GetMetadata
(
const small *
key
,
small *
value
,
UINT64 *
length
)
HRESULT
SetMetadata
(
const small *
key
,
const small *
value
)
BOOL
IsNew
(
)
void
GetVersion
(
MGDFVersion *
version
)
HRESULT
GetVFS
(
IMGDFReadOnlyVirtualFileSystem **
vfs
)
HRESULT
BeginSave
(
IMGDFWriteableVirtualFileSystem **
pending
)
void
ShowCursor
(
BOOL
show
)
BOOL
IsKeyDown
(
UINT16
key
)
BOOL
IsKeyUp
(
UINT16
key
)
BOOL
IsKeyPress
(
UINT16
key
)
INT32
GetMouseX
(
)
INT32
GetMouseY
(
)
INT32
GetMouseDX
(
)
INT32
GetMouseDY
(
)
short
GetMouseDZ
(
)
BOOL
IsButtonDown
(
MGDFMouse
mouseButton
)
BOOL
IsButtonUp
(
MGDFMouse
mouseButton
)
BOOL
IsButtonClicked
(
MGDFMouse
mouseButton
)
UINT64
GetGamepadCount
(
)
void
GetGamepads
(
IMGDFGamepad **
gamepads
)
void
SetLoggingLevel
(
MGDFLogLevel
level
)
MGDFLogLevel
GetLoggingLevel
(
)
void
Log
(
const small *
sender
,
const small *
message
,
MGDFLogLevel
level
)
void
Record
(
double
value
,
const MGDFTags *
tags
)
BOOL
STNew
(
IMGDFSimHost *
host
)
BOOL
STUpdate
(
IMGDFSimHost *
host
,
double
elapsedTime
)
void
STShutDown
(
IMGDFSimHost *
host
)
BOOL
RTBeforeFirstDraw
(
IMGDFRenderHost *
host
)
BOOL
RTDraw
(
IMGDFRenderHost *
host
,
double
alpha
)
BOOL
RTBeforeBackBufferChange
(
IMGDFRenderHost *
host
)
BOOL
RTBackBufferChange
(
IMGDFRenderHost *
host
)
BOOL
RTBeforeDeviceReset
(
IMGDFRenderHost *
host
)
BOOL
RTDeviceReset
(
IMGDFRenderHost *
host
)
void
Panic
(
)
void
GetMetric
(
IMGDFMetric **
metric
)
HRESULT
Begin
(
const MGDFTags *
tags
,
IMGDFPerformanceCounterScope **
scope
)
double
GetAverageValue
(
)
BOOL
GetParent
(
IMGDFReadOnlyFile **
parent
)
BOOL
GetChild
(
const wchar_t *
name
,
IMGDFReadOnlyFile **
child
)
void
GetAllChildren
(
IMGDFReadOnlyFile **
childBuffer
)
BOOL
IsArchive
(
)
void
GetVFS
(
IMGDFReadOnlyVirtualFileSystem **
vfs
)
HRESULT
CopyTo
(
IMGDFWriteableFile *
destination
)
BOOL
GetFile
(
const wchar_t *
logicalPath
,
IMGDFReadOnlyFile **
file
)
void
GetRoot
(
IMGDFReadOnlyFile **
root
)
HRESULT
GetLogicalPath
(
IMGDFReadOnlyFile *
file
,
wchar_t *
path
,
UINT64 *
length
)
BOOL
SetBackBufferRenderTarget
(
ID2D1DeviceContext *
context
)
void
GetBackBuffer
(
ID3D11Texture2D **
backbuffer
)
void
GetDepthStencilBuffer
(
ID3D11Texture2D **
stencilBuffer
)
void
GetBackBufferDescription
(
D3D11_TEXTURE2D_DESC *
backBufferDesc
,
D3D11_TEXTURE2D_DESC *
depthStencilBufferDesc
)
HRESULT
CreateGPUCounter
(
IMGDFMetric *
metric
,
ID3D11DeviceContext *
context
,
IMGDFPerformanceCounter **
counter
)
UINT32
GetMaxFrameLatency
(
)
void
SetMaxFrameLatency
(
UINT32
frames
)
BOOL
GetVSync
(
)
void
SetVSync
(
BOOL
vsync
)
void
GetFullscreen
(
MGDFFullScreenDesc *
fullscreen
)
void
SetFullscreen
(
const MGDFFullScreenDesc *
fullscreen
)
UINT64
GetMultiSampleLevelCount
(
)
BOOL
GetMultiSampleLevel
(
UINT64
index
,
UINT32 *
level
)
BOOL
SetBackBufferMultiSampleLevel
(
UINT32
multisampleLevel
)
UINT32
GetBackBufferMultiSampleLevel
(
)
BOOL
SetCurrentMultiSampleLevel
(
UINT32
multisampleLevel
)
UINT32
GetCurrentMultiSampleLevel
(
UINT32 *
quality
)
UINT64
GetAdaptorModeCount
(
)
BOOL
GetAdaptorMode
(
UINT64
index
,
MGDFAdaptorMode *
mode
)
BOOL
GetAdaptorModeFromDimensions
(
UINT32
width
,
UINT32
height
,
MGDFAdaptorMode *
mode
)
MGDFAdaptorMode *
GetCurrentAdaptorMode
(
MGDFAdaptorMode *
mode
)
BOOL
SetCurrentAdaptorMode
(
const MGDFAdaptorMode *
mode
)
BOOL
SetCurrentAdaptorModeToNative
(
MGDFAdaptorMode *
mode
)
void
SetWindowSize
(
UINT32
width
,
UINT32
height
)
UINT32
GetScreenX
(
)
UINT32
GetScreenY
(
)
void
ApplySettings
(
)
void
GetPreferences
(
IMGDFPreferenceSet **
preferences
)
UINT64
GetSaveCount
(
)
HRESULT
GetSave
(
UINT64
index
,
IMGDFGameState **
save
)
HRESULT
DeleteSave
(
IMGDFGameState *
state
)
void
CreateGameState
(
IMGDFGameState **
save
)
void
GetSaves
(
IMGDFSaveManager **
save
)
void
GetGame
(
IMGDFGame **
game
)
void
GetSound
(
IMGDFSoundManager **
sound
)
void
GetStatistics
(
IMGDFStatisticsManager **
statistics
)
void
GetInput
(
IMGDFInputManager **
input
)
void
ShutDown
(
)
void
QueueShutDown
(
)
HRESULT
GetName
(
wchar_t *
name
,
UINT64 *
length
)
MGDFSoundPosition *
GetPosition
(
MGDFSoundPosition *
position
)
MGDFSoundPosition *
GetVelocity
(
MGDFSoundPosition *
velocity
)
MGDFSoundPosition *
SetPosition
(
MGDFSoundPosition *
position
)
MGDFSoundPosition *
SetVelocity
(
MGDFSoundPosition *
velocity
)
float
GetInnerRange
(
)
void
SetInnerRange
(
float
innerRange
)
float
GetOuterRange
(
)
void
SetOuterRange
(
float
outerRange
)
BOOL
GetSourceRelative
(
)
void
SetSourceRelative
(
BOOL
sourceRelative
)
float
GetVolume
(
)
void
SetVolume
(
float
volume
)
float
GetPitch
(
)
void
SetPitch
(
float
pitch
)
void
SetPriority
(
INT32
priority
)
INT32
GetPriority
(
)
BOOL
GetLooping
(
)
void
SetLooping
(
BOOL
looping
)
void
Stop
(
)
void
Pause
(
)
void
Play
(
)
BOOL
IsStopped
(
)
BOOL
IsPaused
(
)
BOOL
IsPlaying
(
)
BOOL
IsActive
(
)
MGDFSoundPosition *
GetListenerPosition
(
MGDFSoundPosition *
listener
)
MGDFSoundPosition *
GetListenerVelocity
(
MGDFSoundPosition *
velocity
)
MGDFSoundPosition *
GetListenerOrientationForward
(
MGDFSoundPosition *
orientationForward
)
MGDFSoundPosition *
GetListenerOrientationUp
(
MGDFSoundPosition *
orientationUp
)
MGDFSoundPosition *
SetListenerPosition
(
MGDFSoundPosition *
listener
)
MGDFSoundPosition *
SetListenerVelocity
(
MGDFSoundPosition *
velocity
)
MGDFSoundPosition *
SetListenerOrientationForward
(
MGDFSoundPosition *
orientationForward
)
MGDFSoundPosition *
SetListenerOrientationUp
(
MGDFSoundPosition *
orientationUp
)
float
GetSoundVolume
(
)
void
SetSoundVolume
(
float
volume
)
float
GetStreamVolume
(
)
void
SetStreamVolume
(
float
volume
)
BOOL
GetEnableAttenuation
(
)
void
SetEnableAttenuation
(
BOOL
enableAttenuation
)
float
GetDopplerShiftFactor
(
)
void
SetDopplerShiftFactor
(
float
dopplerShiftFactor
)
float
GetSpeedOfSound
(
)
void
SetSpeedOfSound
(
float
speedOfSound
)
HRESULT
CreateSound
(
IMGDFReadOnlyFile *
file
,
INT32
priority
,
IMGDFSound **
sound
)
HRESULT
CreateSoundStream
(
IMGDFReadOnlyFile *
file
,
IMGDFSoundStream **
stream
)
void
GetPreferences
(
IMGDFPreferenceSet **
preferences
)
HRESULT
GetName
(
wchar_t *
name
,
UINT64 *
length
)
float
GetVolume
(
)
void
SetVolume
(
float
volume
)
UINT32
GetPosition
(
)
UINT32
GetLength
(
)
void
Stop
(
)
void
Pause
(
)
HRESULT
Play
(
)
BOOL
IsStopped
(
)
BOOL
IsPaused
(
)
BOOL
IsPlaying
(
)
void
PushString
(
const small *
name
,
const small *
value
,
const MGDFTags *
tags
)
void
PushMetric
(
IMGDFMetric *
metric
)
LARGE_INTEGER
GetCurrentTimeTicks
(
)
LARGE_INTEGER
GetTimerFrequency
(
)
double
ConvertDifferenceToSeconds
(
LARGE_INTEGER
newTime
,
LARGE_INTEGER
oldTime
)
BOOL
Exists
(
)
BOOL
GetParent
(
IMGDFWriteableFile **
parent
)
HRESULT
GetChild
(
const wchar_t *
name
,
IMGDFWriteableFile **
child
)
HRESULT
GetAllChildren
(
IMGDFWriteableFile **
childBuffer
)
HRESULT
OpenWrite
(
IMGDFFileWriter **
writer
)
HRESULT
CreateFolder
(
)
HRESULT
Delete
(
)
HRESULT
MoveTo
(
IMGDFWriteableFile *
destination
)
HRESULT
CopyTo
(
IMGDFWriteableFile *
destination
)
void
GetVFS
(
IMGDFWriteableVirtualFileSystem **
vfs
)
BOOL
GetFile
(
const wchar_t *
logicalPath
,
IMGDFWriteableFile **
file
)
void
GetRoot
(
IMGDFWriteableFile **
root
)
HRESULT
GetLogicalPath
(
IMGDFWriteableFile *
file
,
wchar_t *
path
,
UINT64 *
length
)
UINT32
Width
UINT32
Height
UINT32
RefreshRateNumerator
UINT32
RefreshRateDenominator
BOOL
FullScreen
BOOL
ExclusiveMode
float
x
float
y
float
z
const small **
Names
const small **
Values
UINT64
Count
INT32
Major
INT32
Minor
INT32
Build
INT32
Revision