TDME2  1.9.200
TDME2 Documentation

License: MIT NIX Build Status MacOSX Build Status Windows/MINGW Build Status Windows/MSC Build Status Coverity Scan Build Status

LOGO

1. What is TDME2?

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, 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, 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
  • 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
      • sha256
      • 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

7.2. External references

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