1. What is TDME2?

• ThreeDeeMiniEngine2 is a lightweight, multiplatform 3D engine including tools
  • Read about the philosophy if interested
  • See screenshots, if you want to quickly know where we are and where we will go :)
• TDME2 is open source
  • please check the license
  • you find the source code at https://github.com/Mindty-Kollektiv/tdme2
  • you find binary alpha builds at https://www.mindty.com/products/tdme2/builds/
  • here you find developer documentation including collaboration graphs and private API as well as public API for current alpha build
    • RapidJSON is included, but not yet integrated into documentation, please see http://rapidjson.org/
    • For TDME2 GUI XML documentation see README-GUI-XML.md
    • For TDME2 MiniScript documentation
      • see README-MiniScript.md
      • here you find base MiniScript documentation including collaboration graphs and API

2. Features

• Application
  • initialization
    • loads and initializes renderer backend plugin
    • creates main window and OpenGL/Vulkan context using GLFW3
  • handles HID
  • supports
    • setting window position and dimension
    • setting full screen or windowed, borderless windowed mode
    • setting application icon
    • setting mouse position and mouse cursor
    • executing other applications or background applications
    • swapping double buffered buffers (to screen) manually if required
    • checking if application is active (port-mingw, port-msc only for now)
    • setting and getting data from clipboard
    • receives and forwards file/folder drop events
    • gamepads/joysticks (WIP)
  • provides
    • a crash handler for port-msc and port-mingw which also saves backtrace to crash.log
    • application life cycle
• Math
  • Math class with common math functions
  • Vector2, Vector3, Vector4, Matrix3x3, Matrix4x4 and Quaternion class
    • those have a ordinary API + operators, the latter is still a bit WIP
• 3D engine
  • model reader
    • DAE
      • node names/ids must not have whitespace characters
      • requires baked matrices
      • requires triangulated meshes for now
    • FBX via FBX SDK
    • GLTF via tinygltf
    • TDME Model file format
      • this is a much more efficient model file format for TDME
      • can also be written
      • can use external or embedded PNG and embedded BC7 textures
  • objects/entity types
    • 3d model based objects with
      • animations
        • supports model object base animation and animation overlays
        • supports animation blending
      • skinning via
        • CPU on GL2, GL3+/CORE, GLES2
        • GPU via compute shaders with GL4.3+/CORE, Vulkan, GL3+/CORE via OpenCL for MacOSX
        • which also supports several instances of the same object to reduce compute and render calls
      • both animations and skinning have some sort of configurable LOD functionality
      • texture transforms/animations
        • via texture matrices
      • supports BC7 texture compression
    • objects with support for LOD
    • imposter objects with support for LOD
    • render group objects for foliage and such including LOD support
    • particle systems which
      • are object based
      • or point based, including sprite sheet animation support
      • or for fog purposes, including sprite sheet animation support
      • and support
        • basic/point emitter
        • sphere emitter
        • bounding box emitter
        • circle on plane emitter
        • ...
      • there is also support for particle system groups
    • lines based objects
    • entity hierarchy objects
    • environment mapping objects
      • which can be used as reflection sources of other objects
    • decal objects, including sprite sheet animation support
  • object/entity transforms
    • scaling
    • rotations
    • translation
  • color effects on objects/entities
    • color addition
    • color multiplication
  • lighting
    • supports specular lighting
      • supports phong lighting
      • supports phong shading on GL2, GL3+/CORE, Vulkan
      • supports gouraud shading on GLES2
      • supports diffuse mapping on GLES2, GL2, GL3+/CORE, Vulkan
      • supports specular shininess mapping on GL3+/CORE, Vulkan
      • supports normal mapping on GL3+/CORE, Vulkan
      • supports reflection mapping from cube maps on GLES2, GL2, GL3+/CORE, Vulkan
    • supports PBR lighting with IBL
    • supports deferred shading and forward shading on GL3+/CORE, Vulkan
  • custum shaders that currently include
    • specular lighting
    • specular lighting + foliage
    • specular lighting + tree
    • specular lighting + terrain
    • specular lighting + water
    • sky
    • PBR lighting
    • PBR lighting + foliage
    • PBR lighting + tree
  • shadow mapping
  • post processing
    • depth blur
    • desaturation
    • light scattering
    • SSAO
    • vignette
  • object picking
  • camera control
    • set up look from, look at, up vector can be computed
    • frustum culling via oct tree
  • supports offscreen instances
    • rendering can be captured as screenshot
    • rendering can be used (in other engine instances) as diffuse texture
  • supports down/up scaled rendering of main engine
  • screenshot ability
  • multiple renderer backends, which are loaded at runtime
    • GLES2, GL2, GL3+/CORE and Vulkan
• Physics via ReactPhysics3D 0.9.0
  • have sphere, capsule, obb, convex mesh, concave terrain mesh, height map bounding volumes
  • have multiple bounding volumes per body
  • have static, dynamic rigid bodies and collision bodies
  • have joints(WIP)
  • uses discrete collision detection
  • rigid body simulator
  • ray tracing
  • for RP3D internals and additional features see ReactPhysics3D website
• Path finding/flow maps
  • uses A*
  • is paired with physics world to determine if a "cell" is walkable
  • optional custom walkable test
  • additional optional navigation map test
  • path finding utility supports generating flow maps
• 3D audio
  • decoder
    • ogg vorbis decoder
  • audio entities
    • streams
    • sounds
• Video
  • decoder
    • mpeg1 decoder
• GUI system
  • borrows some ideas from Nifty-GUI regarding XML and layouting
  • borrows some ideas from AngularJS like
    • all nodes are in the GUI node tree and can be made visible or unvisible depending on conditions
  • adds some improvements like
    • support auto keyword with nodes width and height attributes
    • layouting on demand in combination with conditions
  • supported primitive nodes from which compounds are built of
    • element
    • gradient
    • image(plus framebuffer and texture image nodes)
    • input
    • layer
    • layout
    • panel
    • scrollbars
    • space
    • table
    • text + multiline/styled text
    • video
  • supports custom templates and compound elements defined by templates and its controllers
    • compound elements
      • button
      • checkbox
      • dropdown
      • grid (needs some love still)
      • image button
      • input
      • knob
      • menu
      • progress bar
      • radio button
      • scrollarea
      • selectbox including tree view
      • selector horizontal
      • slider horizontal
      • slider vertical
      • tabs
      • moveable
    • supports custom templates in general
    • supports overriding used template of a compound element while using its controller
    • so TDME2 GUI is fully customizable in terms of appearance by modifying or adding XML template definitions
  • includes a simple script language
    • to react on events with like on-mouse-click, ... and on-change for elements
    • to manipulate conditions of elements, values of element controller and node properties
  • a MiniScript script can be attached to screen nodes
    • to react on events
    • to modify the gui nodes tree or gui nodes state
    • to implement GUI application flow(WIP)
  • supports position and color based effects in combination with conditions that can also be defined via XML
  • unicode support via UTF8
• MiniScript
  • very small implementation of a scripting language
  • runs on every CPU, OS, ... due to its simplicity, so its highly portable just like TDME2 is
  • can be easily extended by writing state machine machine states and script methods in C++ as well as custom data types
  • built-in data types: null, boolean, integer, float, string, vector2, vector3, vector4, quaternion, matrix3x3, matrix4x4, transform, byte array, array, map and set
  • when calling script C++ methods or script functions with arguments it does optionally use references or value by copy
  • supports user script functions and recursion
  • supports operators by operator to method mapping by a preprocessor run
  • supports loops and conditions
  • supports programming with classes style programming
    • for built-in datatypes: string, vector2, vector3, vector4, quaternion, matrix3x3, matrix4x4, transform, byte array, array, map and set
    • for script classes/objects
    • for custom data types
  • supports event like programming
  • can be transpiled to C++
  • how to use:
    • each script is attached to a game entity
    • communication between script instances is possible by
      • using callable functions
      • sending signals with arguments
    • complex logic should still be implemented by a game developer in C++ by extending MiniScript
    • game designers can use MiniScript + those methods to implement high level game logic
  • MiniScript methods/states know about them self, so a whole documentation for MiniScript usage can be generated later
• Networking module, which consists of
  • UDP server
    • n:m threading model with non blocked IO via kernel event mechanismns(epoll, kqueue or select)
    • supports safe messages with acknowledgment and automatic resending
    • supports fast messages
    • can be used in a heavy multithreaded environment (the networking module is thread safe)
    • IPV6 ready
  • UDP client
    • has single thread with a simple threadsafe API
    • supports all features required by UDP server
    • IPV6 ready
  • Simple HTTP client
    • uses a blocking TCP socket, thus it has a simple blocking API
    • Ready for REST providing all methods, setting content type and body
    • be able to set GET and POST parameters via unordered map
    • supports basic authentification
    • IPV6 ready
  • HTTP download client
    • supports basic authentification
    • uses a separate thread to download to file
    • IPV6 ready
• Operating system abstraction layer
  • file system
    • standard file system
    • zlib based compressed archive file system and a tool to generate it from ./resources and ./shader folder
    • unicode support via UTF8
  • multi threading
    • atomic operations
    • barrier
    • condition
    • consumer/producer queue
    • mutex
    • read write lock
    • spin lock
    • thread
• Application server and application client on top
  • each one owns a context to store logics and global app/game state at least, so context
    • also has some additional UDP specific network functionality
    • has easy polling like access to underlying path finding threads
    • does logics management and execution in a separate thread
  • application server and client threads also do physics computations
  • logics which do live in application server context and application client context are capable of
    • update engine entities if living in application client and also update UI and such
    • executing app/game logic that change logic state, which can be visualized(see point above) and/or synched by network
    • easy access to manage audio playback
    • handling HID input
    • doing network sync

3. Tools

• Editor
  • This is our content editor, please see README-Editor.md
• Installer
  • TDME2 itself and TDME2 applications can be installed with TDME2 installer, which supports
    • offline installations
    • installation using HTTP download from a repository which is easy to set up
    • updating/repairing/uninstalling
  • TDME2 tools contains the installer creation application, whereas
    • installer definitions are set up using property files
    • create-installer is able to group files into components
• Other tools
  • archive tool to generate a single compressed file file system from ./resources and ./shader folders
  • converttotm tool to generate TDME2 model files
  • createinstaller tool to generate installer application and archives
  • generatelicenses tool to generate complete engine or project licenses from ./ext folders
  • importtmodel tool to generate TDME2 tmodel prototype files using model and bounding volumes models
  • makefilegenerator and nmakefilegenerator tool to generate Makefiles for TDME2 based projects
  • miniscript command line tool to execute MiniScript scripts
  • createminiscriptcodecompletion tool to generate code completion database for MiniScript
  • createminiscriptdocumentation tool to generate documentation for MiniScript methods and operators
  • miniscripttranspiler tool to transpile MiniScript code to C++ code
  • optimizemodel tool to generate texture atlases and bake down model mesh nodes into a few one to reduce GL/VK (render/compute) calls
  • sortincludes tool to sort "include" and "using" source code statements
  • others ...

4. What does it (maybe still) lack

• physics
  • some more RP3D integration
• example games
• documentation

5. What is WIP or planned for first BETA

• MiniScript: more engine bindings(WIP)
• Editor: Code editing with code completion, also visual code editing is planned! (wip)
• Visual animation blending/system editor
• Shaders: Implement a new more abstract shader system using e.g. shader parameter system and add a visual/code shader editor on top
• Particle System: overhaul
• Lights: finish implementing the light system, modernize it also a bit + bloom effect for emissive materials
• Editor: complete Undo/Redo and Copy/Cut/Paste/Delete
• Cascaded Shadow Mapping
• Vulkan: Performance improvements
• PBR: generate IBL cube maps from scene (need to wait for WS PBR assets to finalize)
• Reflections via environment mapping(reflection intensity maps feature is missing for specular materials)
• GUI effects via XML definitions (already working, needs bugfixes)
• Optimizing models with specular lighting regarding render calls by reducing nodes and materials to a minumum (working already, needs to be finished)
• Some UI elements need some focus/disabled fixes
• Lots of minor bug fixes and user experience improvements
• A release plan
• A demonstration video

6. Technology

• designed for simple multi threading, but
  • 3D rendering engine uses multiple threads if using Vulkan renderer, or one thread only if using a GL renderer
  • UDP client has its own thread
  • UDP server can have multiple IO threads, multiple worker threads and always has its own server thread
  • HTTP download client has its own thread
  • physics or game mechanics can also run in a separate thread(s)
  • application server has its own thread
  • application client has its own thread
  • application context can have multiple path finding threads and does at least have one thread
• uses 3rd party libraries
  • needs to be installed, if not using port-msc
    • OpenGL
    • OpenAL
    • glew
    • GLFW3
    • freetype2
    • xml2(port-linux for FBXSDK)
    • Vulkan(optional)
  • included in TDME2 repository
    • bc7enc_rdo
    • cpp-spline
    • FBXSDK
    • libpng
    • pl_mpeg
    • ReactPhysics3D
    • RapidJSON
    • tinygltf
    • tinyxml
    • V-HACD
    • Vorbis/OGG
    • Vulkan
      • glslang
      • OGLCompilersDLL
      • simple_vulkan_synchronization
      • spirv
      • VulkanMemoryAllocator
    • zlib
• targeted platforms and its current state
  • Windows/MINGW(port completed)
  • Windows/MSC(port completed)
  • Linux(port completed)
  • MacOSX(port completed)
  • FreeBSD(port completed)
  • NetBSD(port completed)
  • OpenBSD(port completed)
  • Haiku(port completed)
  • Android(port pending)
  • iOS(port pending)

7. Other information

7.1. Links

• TDME2 Philosophy, see README-Philosophy.md
• TDME2 Engine, see README.md
• TDME2 Editor, see README-Editor.md
• TDME2 How to build, see README-BuildingHowTo.md
• TDME2 Screenshots, see README-Screenshots.md
• The Mindty Kollektiv Discord Server

7.2. External references

• "ReactPhysics3D" physics library, http://www.reactphysics3d.com
• the world wide web! thank you for sharing, see README-WebReferences.md

7.3. Other credits

• Dominik Hepp
• Mathias Lenz
• Kolja Gumpert
• Mathias Wenzel
• Sergiu Crăiţoiu
• Chantal Zabel
• others

7.4. Special thanks go to

• Kristin Meissner
• Dominik Hepp

8. Collaboration

• Interested in collaboration? Then drop me a line via mail or use the issues section on tdme2@github or on tdme2@codecks
  • You can help with testing and reporting bugs
  • I have easy to hard task regarding engine/tools development
  • I have tasks regarding documentation
  • I even might have system administrator tasks

9. Donation

• I have to pay my bills, beer and stuff, so if you have any use for this open source project, like educational, productive or fun, ..., consider a donation here PayPal, here GitHub Sponsors or via Amazon Wishlist