VGFramework 0.52

VGFramework is a pet game engine for fun, modern graphics APIs, and fast iteration.

Table of contents

Build status
Getting started
Licence
Extern libs
Assets
Misc

Build status

Configuration	Debug	Development	Release	Final
ARM64EC MSVC DX12
ARM64EC MSVC Vulkan
Win64 MSVC DX12
Win64 MSVC Vulkan
Win64 ClangCL DX12
Win64 ClangCL Vulkan

Getting started

You have two options depending on whether you want to build from source or use the provided executables:

Using precompiled binaries (users)

• Run editor.exe to launch the editor.
• Run game.exe to start the game.

Building from sources (programmers)

By default, VGFramework uses the precompiled binaries: editor.exe, game.exe, and the DLLs located in the bin/ folder.

When you build locally, executable files will be created in your build/ folder.
The program will use these locally built files if they are present; otherwise, it will fallback to the precompiled binaries.

To build from sources:

• Sync the depot.
• Install the required SDKs and configure the environment variables.
• Generate solution and open it in your favorite development environment.
• Select solution Configuration and Platform
• Select the solution folder for Working Directory
• Build & Run

Debug, Development and Release versions will start with the editor: Press F5 to enter game mode and F11 to maximize game view and press ESC to go back Editor mode.

Final versions are compiled without the editor, they will start directly in game mode and maximized.

First run might take a few seconds because files are cooking.

Generate solution

VGFramework is using Sharpmake to generate its solution and projects files for all supported platforms.\

You can generate the solutions using sharpmake\generates_projects_XXX.bat where XXX is your development environment.

e.g. sharpmake\generates_projects_Windows.bat will generate vgframework_vs2022.sln with all Windows targets.

Config	Description	Format	Files
generate_projects_Windows.bat	All Windows targets	Visual Studio 2022	*.sln; *.vxcproj; *.vcxproj.filters
generate_projects_Windows_msvc.bat	MSVC Windows targets only	Visual Studio 2022	*.sln; *.vxcproj; *.vcxproj.filters
generate_projects_Windows_arm64ec.bat	ARM64EC Windows targets only	Visual Studio 2022	*.sln; *.vxcproj; *.vcxproj.filters
generate_projects_macOS.bat	All macOS targets	XCode	*.xcodeproj
generate_projects_Linux.bat	All Linux	Make	makefile

generate_projects_Windows_msvc.bat and generate_projects_Windows_arm64ec.bat have been added for convenience if you don't have the Clang compiler installed or you are working on an ARM Surface Pro device.

You can customize the targets to build using the following switchs:

Name	Type	Description
arm64ec	bool	Generate ARM64EC platform targets
win64	bool	Generate Win64 platform targets
msvc	bool	Generate MSVC compiler targets
clang	bool	Generate Clang compiler targets
dx12	bool	Generate DX12 API targets
vulkan	bool	Generate Vulkan API targets

e.g.:

.\bin\windows\Sharpmake.Application.exe "/sources('main.sharpmake.cs') /generateDebugSolution /debugSolutionPath('debug/Windows') /win64(true) /arm64ec(false) /clang(false) /msvc(true) /dx12(true) /vulkan(false)"

will generate only the Win64 targets using the MSVC compiler and the DirectX12 API.

IDE

Recommended IDE is VS Studio 2022 Community and project files currently provided are compatible with this version.

However, the engine is currently being ported to other platforms than Windows so ultimately a project generator solution will be used.

To compile the solution you will need the following components if they are not already installed:

• MSVC v143 - VS 2022 C++ x64/x86 build tools (latest)
• C++ ATL for latest v143 build tools (x86 & x64)

You will also need if you want to build the ARM64EC versions:

• MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (latest)
• C++ ATL for latest v143 build tools (ARM64/ARM64EC)

Solution Configuration

Use the 'Configuration' combo to select build configuration:

Config	#define	Runtime	Optimization	Inlining	Edit & Continue	Assert
Debug	VG_DEBUG	/MDd	/Od	/Ob0	Yes	Yes
Development	VG_DEVELOPMENT	/MD	/Od	/Ob0	Yes	Yes
Release	VG_RELEASE	/MD	/O2	/Ob2	No	Yes
Final	VG_FINAL	/MD	/O2	/Ob2	No	No

The recommended default configuration is Development as it's a good compromise between debugging information, performance and it allow 'Edit & Continue'.

Solution Platform

Use the 'Platform' combo to select target architecture and graphics API:

The recommended default solution under Windows is Win64 MSVC DX12 as it's the primary OS, compiler, and API used by the author.

Working Directory

Set your working directory to $(SolutionDir) so that the program can find data and code.

Command-line args

Name	Type	Description
attachDebugger	bool	MessageBox at application start to let attach a debugger
breakOnErrors	bool	Break on graphics API errors (debugDevice required)
breakOnWarnings	bool	Break on graphics API warnings (debugDevice required)
debugDevice	bool	Enable the graphics API debug layer (default for Debug builds)
editor	bool	Enable editor (default for Debug and Release builds)
fullscreen	bool	Start application with game view maximized (default for Final builds)
play	bool	Start application with play mode running (default for Final builds)
profileStart	int	Profile the 1st N frames

Keyboard shortcuts

Name	Description
A	Toggle snap
F	Focus Selection
H	Toggle HDR modes (None, HDR10, HDR16)
V	Toggle VSync mode (None, 1 VBL, 2 VBL, 3 VBL, 4 VBL)
UP	Move editor camera forward
LEFT	Move editor camere left
DOWN	Move editor camera backward
RIGHT	Move editor camere right
F1	Start/stop profiler capture
F2	Rename selected Object
F6	Hot reload shaders
F7	Hot reload resources
F5	Enter Play mode
Shift-F5	Restart Play mode
PAUSE	Pause/resume Play mode
F11	Maximize Game view (fullscreen)
ESCAPE	Exit Play mode and go back to Editor mode
DELETE	Delete selected objects
Ctrl+Mouse Wheel	Toggle Translation/Rotation/Scale gizmo
Ctrl+D	Duplicate selected objects.
Shift+Translate	Keep shift pressed while moving objects to duplicate objects.
Ctrl+S	Save
Ctrl+U	Save Prefab & Update
Ctrl+Shift-Q	Quit application

SDKs

The SDKs are not included with the sources. You need to install them.

Name	Version
Win10 SDK	10.0.26100.0
.Net	6.0
Vulkan SDK	1.3.290.0

Win10 SDK and .Net 6.0 Runtime can be installed directly from Visual Studio in Tools > Get Tools and Features ...

.Net 6.0 Runtime is only required for project generation using Sharpmake.

Vulkan SDK is only required to build Vulkan version. $(VULKAN_SDK) should point the Vulkan SDK installation dir (e.g., C:\SDK\Vulkan\1.3.290.0).

Extern libs

The external libraries are included with the sources for convenience. Follow the link for details about the licence used.

Name	Version
D3D12 Memory Allocator
D3D12 HDR Sample
Dear ImGui - Docking	1.92.5
DirectX Shader Compiler	1.8.2505.1
Dirent	1.23.2
fmt	10.1.1
FXAA	3.11
hlsl++	3.7
IconFont CppHeaders
ImGuiFileDialog	0.6.7
ImGuizmo	1.83
JoltPhysics	5.0.0
meta_enum_lite	2.0 (Custom)
optick ✨	1.3.1
px_sched
Sharpmake	0.75.0 (Custom)
SoLoud	August 2024
stb	2.30
tinyXML2	10.0.0
UFBX	0.14.3
Vulkan Memory Allocator	3.0.1
WinPixEventRuntime	1.0.231030001

✨ Optick viewer can be tricky to build but you can download the binaries for optick 1.3.1 from https://github.com/bombomby/optick/releases/tag/1.3.1.0 or build them more easily from https://github.com/vimontgames/optick.

Licence

Code

The code in src folder is licensed under the MIT License. Please refer to LICENCE.md for more details.

External libraries in the extern folder use permissive licenses. Please refer to the Extern libs section for details about the licenses used.

Data

Most assets are using permissive licenses, while some are restricted to use only within the context of VGFramework development. Please refer to the Assets section for more details about the licenses used.

Assets

Assets with usage restrictions

The assets in the following folders are licensed under the Creative Commons Non-Commercial (CC BY-NC 4.0) License, with the additional restriction that they may only be used within the context of VGFramework development.

Please refer to the ASSETS_LICENSE.md for more details.

Asset folders	Author
data/Meshes/GJ data/Textures/GJ	JOYxt
data/Meshes/VGF_Bo data/Textures/VGF_Boy	JOYxt
data/Meshes/GrosCovid data/Textures/GrosCovid	JOYxt

Other assets

The following assets are provided under permissive licenses. Please follow the provided links for details about those licenses:

Fonts

Name	Version
Font-Awesome	6.x
Rowdies
RubikMonoOne
UbuntuMono	1.0

Models

The following models have been modified for engine-compatible materials and/or geometry adjustments.

Name	Author
3D Football	prabath-weerapana
Baseball Bat	sepandjahrominejad
FootBall american	orsbone
Katana samurai sword	kizaru
Luigi	Anthony Yanez
Traffic Cone	hinndia
Soccergoal	NorbertVarga
Traffic Light	Dastan-Persia
Clio Williams	Mona x Supercars
Modern outdoor bench	VVei

Textures

Name	Author
Concrete020	ambientcg.com

Environment maps

Name	Author
Free HDR Map 779	hdri-skies.com

Sounds

Name	Author
FX - Swoosh - normal	bolkmar
Large sword swing	Luis0413
Tally Dub	Brotheration Records
Chainsaw	pblzr
Retro Bonus Pickup	suntemple
Broken mirror	urupin
The broken mirror	urupin
Car door	RutgerMuller

Misc

These tools are not mandatory but can be useful for development.

Name	Info
Radeon Developer Panel	GPU debugging & profiling
RenderDoc	GPU debugging