VGFramework 0.53

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	License
D3D12 Memory Allocator		MIT
D3D12 HDR Sample		MIT
Dear ImGui - Docking	1.92.5	MIT
DirectX Shader Compiler	1.8.2505.1	LLVM
Dirent	1.23.2	MIT
fmt	10.1.1	MIT
FXAA	3.11	Apache 2.0
hlsl++	3.7	MIT
IconFont CppHeaders		Zlib
ImGuiFileDialog	0.6.7	MIT
ImGuizmo	1.83	MIT
JoltPhysics	5.0.0	MIT
meta_enum_lite	2.0 (Custom)	MIT
optick ✨	1.3.1	MIT
px_sched		MIT
Sharpmake	0.75.0 (Custom)	Apache 2.0
SoLoud	August 2024	Zlib/libpng
stb	2.30	MIT
tinyXML2	10.0.0	Zlib
UFBX	0.14.3	MIT/Public Domain
Vulkan Memory Allocator	3.0.1	MIT
WinPixEventRuntime	1.0.231030001	MIT

✨ 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:

Animations

This project uses character animations generated via Mixamo.

Fonts

Name	Version	License
Font-Awesome	6.x	Font Awesome Free License / CC BY 4.0 / SIL OFL 1.1
Rowdies		SIL OFL 1.1
RubikMonoOne		SIL OFL 1.1
UbuntuMono	1.0	Ubuntu Font Licence

Models

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

Name	Author	License
3D Football	prabath-weerapana	Royalty Free Licence (no AI)
Baseball Bat	sepandjahrominejad	Royalty Free Licence (no AI)
FootBall American	orsbone	Royalty Free Licence (no AI)
Katana Samurai Sword	kizaru	Royalty Free Licence (no AI)
Traffic Cone	hinndia	Royalty Free Licence (no AI)
Modern Outdoor Bench	VVei	Royalty Free Licence (no AI)
Traffic Light	Dastan-Persia	Royalty Free Licence (no AI)
Luigi	Anthony Yanez	TurboSquid 3D Model License
Soccergoal	NorbertVarga	TurboSquid 3D Model License
Clio Williams	Mona x Supercars	CC BY 4.0
Generic Passenger Car Pack	Comrade1280	CC BY 4.0
GJ	JOYxt	CC BY-NC 4.0 VGF
VGF_Boy	JOYxt	CC BY-NC 4.0 VGF
GrosCovid	JOYxt	CC BY-NC 4.0 VGF

Textures

Name	Author	License
Concrete020	ambientcg.com	CC0 1.0

Sounds

Name	Author	License
FX - Swoosh - normal	bolkmar	CC0 1.0
Chainsaw	pblzr	CC0 1.0
Retro Bonus Pickup	suntemple	CC0 1.0
Car door	RutgerMuller	CC0 1.0
Industrial Air Horn	mcpable	CC0 1.0
boat ship barge	kyles	CC0 1.0
Car Horn Honk	etcd_09_	CC BY 3.0
Car Breaking Skid	Medartimus	CC BY 4.0
Large sword swing	Squirrel_404	CC BY 4.0
Broken mirror	urupin	CC BY-NC 4.0
Rally Car Idle Loop	DebSound	CC BY-NC 4.0

Misc

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

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