WickedEngine

# Wicked Engine

Wicked Engine is an open-source 3D engine with modern graphics. Use this as a C++ framework for your graphics projects, a standalone 3D editor, LUA scripting or just for learning.
- [Website](https://wickedengine.net/)
- [Features](features.txt)
- [Editor Manual](Content/Documentation/WickedEditor-Manual.pdf)
- [C++ Documentation](Content/Documentation/WickedEngine-Documentation.md)
- [Lua Documentation](Content/Documentation/ScriptingAPI-Documentation.md)
- [Videos](https://www.youtube.com/playlist?list=PLLN-1FTGyLU_HJoC5zx6hJkB3D2XLiaxS)
You can get the full source code by using Git version control and cloning https://github.com/turanszkij/WickedEngine.git, or downloading it as zip. You can also download nightly packaged builds of the Editor here (requires Github sign in): [](https://github.com/turanszkij/WickedEngine/actions)
### Platforms: - Windows - Linux - Mac OS - iOS - Xbox Series X|S - PlayStation 5 ### How to build: #### Windows To build Wicked Engine for Windows, open the `WickedEngine.sln` solution file with the latest Visual Studio. When it's opened, press F5, then Wicked Engine and the Editor application will be built and then start. You can check out other sample projects in the solution too. If you want to develop a C++ application that uses Wicked Engine, you can build the WickedEngine_Windows static library project and link against it. Including the `"WickedEngine.h"` header will attempt to link the binaries for the appropriate platform, but search directories should be set up beforehand. For example, you can set additional library directories to `$(SolutionDir)BUILD\$(Platform)\$(Configuration)` by default. For examples, see the `Samples/Template_Windows`, `Samples/Tests`, and `Editor_Windows` projects. You can also use cmake to build on windows with these commands: ``` cmake -B build cmake --build build --config Release ``` #### Linux To build the engine for Linux, use Cmake. You can find a sample build script for Ubuntu [here](.github/workflows/build.yml) (in the linux section). On Linux you will need to ensure some additional dependencies are installed, such as Cmake (3.7 or newer), g++ compiler (C++ 17 compliant version) and SDL2. You can use the following commands to install dependencies: ```bash sudo apt update sudo apt install libsdl2-dev sudo apt install build-essential ``` Example commands to build the engine with cmake in Release mode: ```bash mkdir build cd build cmake .. -DCMAKE_BUILD_TYPE=Release make ``` #### Mac OS and iOS To build the engine for Mac OS and iOS, use the provided .xcodeproj files with the Xcode development environment, for example: - WickedEngine/WickedEngine.xcodeproj to build static library - Editor/Editor.xcodeproj to build the Wicked Editor - Samples/Template_MacOS/Template_MacOS.xcodeproj to build a minimal template application for MacOS that you can use as a base for your application - Samples/Template_iOS/Template_iOS.xcodeproj to build a minimal template application for iOS that you can use as a base for your application #### Xbox Series X|S and PlayStation 5 Console specific extension files required for building are currently private. ### Examples: #### Initialization (C++): ```cpp // Include engine headers: #include "WickedEngine.h" // Create the Wicked Engine application: wi::Application application; // Assign window that you will render to: application.SetWindow(hWnd); // Run the application: while(true) { application.Run(); } ``` #### Basics (C++): ``` … ``` #### Scripting (LUA): ``` … ``` (You can enter lua scripts into the backlog (HOME button), or the startup.lua script which is always executed on application startup if it is found near the app, or load a script via dofile("script.lua") command) For more code samples and advanced use cases, please see the example projects, like the Template_Windows, Tests, or Editor project. There are also sample models and scripts included with Wicked Engine in the Content/models and Content/scripts folders. Check them out to learn about more features. ### Scripting API: You can use a lot of of engine features through Lua scripting. The included applications, like the Editor, contain a scripting input method toggled by the "Home" key. A text screen will be presented where the user can type in LUA commands. For further details, check the scripting API documentation: [Wicked Engine Scripting API](Content/Documentation/ScriptingAPI-Documentation.md) ### Model import/export: The native model format is the WISCENE format. Any application using Wicked Engine can open this format efficiently. In addition, the Editor supports importing some common model formats: - OBJ - FBX - GLTF, GLB - VRM, VRMA - PLY You can import models into the Editor, and save them as WISCENE, then any Wicked Engine application can open them.
### Graphics API: The default renderer is `DirectX 12` on Windows, `Vulkan` on Linux and `Metal` on Apple systems. You can specify command line arguments (without any prefix) to switch between render devices or other settings. Currently the list of options: Argument Description vulkan Use the Vulkan rendering device on Windows debugdevice Use debug layer for graphics API validation. Performance will be degraded, but graphics warnings and errors will be written to the "Output" window gpuvalidation Use GPU Based Validation for graphics. This must be used together with the debugdevice argument. Currently DX12 only. gpu_verbose Enable verbose GPU validation mode. igpu Prefer integrated GPU selection for graphics. By default, dedicated GPU selection will be preferred. amdgpu Prefer AMD GPU selection for graphics. nvidiagpu Prefer Nvidia GPU selection for graphics. intelgpu Prefer Intel GPU selection for graphics. alwaysactive The application will not be paused when the window is in the background.
### Other software using Wicked Engine - Wicked Shooter: FPS sample game in Wicked Engine - Wicked Adventure: Adventure RPG sample game in Wicked Engine - Grass Zen: A relaxing game made with Wicked Engine where you control the wind - Game Guru MAX: Easy to use game creator - Flytrap: Demoscene production by qop - doddering: Demoscene production by qop - Your project: add your project to this readme and open a pull request
### Troubleshooting If you are having trouble getting the applications to run, make sure that you satisfy the following conditions: - If you built the application with Visual Studio, run it from the Visual Studio environment, where the executable working directory is set up to be the Project directory (not the build directory where the exe will be found) - If you want to run an application without Visual Studio, either copy the executable from the BUILD directory to the correct project directory, or set the working directory appropriately. You can also check the Working directory setting in Visual Studio to find out the right working directory of every project. - If you experience crashes, you can try these to find out the problem: - make sure your environment is up to date, with latest graphics drivers and operating system updates. - see if there is a log.txt in the working directory of the application (most likely near the application exe) - request help on [Discord](https://discord.gg/CFjRYmE) or via a [Github issue](https://github.com/turanszkij/WickedEngine/issues) - build the engine in Debug mode and try to run it, see where it crashes - run the engine with the `debugdevice` command argument and post the text from your console output window when the crash happens - for very advanced users, using `gpuvalidation` with `debugdevice` will print additional graphics debug information