Engine² Tools

A comprehensive C++ utility library providing essential tools and utilities for the Engine² game engine ecosystem. This module contains reusable components for logging, function containers, and various development utilities designed to support 3D game development workflows.

Overview

Engine² Tools is part of the Engine² (Engine Squared) project, an open-source physics game engine developed as an Epitech 4th/5th year end project (EIP). This repository provides three core utility modules:

• Log - Advanced logging framework built on spdlog
• Function Container - Type-safe function wrapper and callback management
• Tools - General-purpose utility functions and helpers

Purpose

This library provides developer-friendly, production-ready utilities that:

• Simplify common development tasks in game engine projects
• Provide consistent logging and debugging capabilities
• Enable flexible event-driven programming through function containers
• Maintain high code quality with comprehensive unit testing

Primary Use Cases

• Game Engine Development: Core utilities for Engine² and derivative projects
• C++ Game Projects: Reusable components for any C++20 game development
• Event Systems: Building callback-based architectures with type-safe function containers
• Debugging & Monitoring: Structured logging for complex game systems

---

Installation

Prerequisites

• C++20 compatible compiler (GCC 10+, Clang 11+, MSVC 2019+)
• Xmake build system (v2.5.0 or higher)

Dependencies

The following dependencies are automatically managed by Xmake:

• spdlog v1.16.0 - Fast C++ logging library
• fmt v12.1.0 - Modern formatting library
• gtest v1.17.0 - Google Test framework (for unit tests)

Build Instructions

1. Clone the repository

   git clone https://github.com/EngineSquared/Tools.git
   cd Tools

2. Build the library

   xmake build

   To automatically install dependencies:

   xmake build -y

3. Run unit tests

   xmake test

   Or with automatic dependency installation:

   xmake test -y

Build Modes

• Debug mode (default): Includes debugging symbols and assertions

  xmake f -m debug
  xmake build

• Release mode: Optimized for performance

  xmake f -m release
  xmake build

Integration

Add EngineSquaredTools as a dependency in your xmake.lua:

add_deps("EngineSquaredTools")
add_packages("spdlog", "fmt")

---

Configuration

Build Configuration

The library supports several build options in xmake.lua:

# Build with all examples
xmake f --all_examples=y
xmake build

# Build specific example (e.g., logger_usage)
xmake f --logger_usage=y
xmake build

# Build executable examples only
xmake f --executable_examples=y
xmake build

Compiler Flags

Debug Mode:

• Defines: DEBUG, ES_DEBUG
• Windows: /Od /Zi /Wall /MTd
• Linux/macOS: -O0 -g3 -ggdb

Release Mode:

• Defines: NDEBUG
• Optimization: -O2

---

Available Commands

Build Commands

Command	Description
xmake build	Build the library
xmake build -y	Build with automatic dependency installation
xmake clean	Clean build artifacts
xmake rebuild	Clean and rebuild

Test Commands

Command	Description
xmake test	Run all unit tests
xmake test -v	Run tests with verbose output
xmake test -y	Run tests with automatic dependency installation

Example Commands

Command	Description
xmake f --all_examples=y && xmake build	Build all examples
xmake f --logger_usage=y && xmake build	Build logger example
xmake f --function_container_usage=y && xmake build	Build function container example
xmake run LoggerUsage	Run logger example
xmake run FunctionContainerUsage	Run function container example

Documentation Commands

Command	Description
doxygen Doxyfile.cfg	Generate API documentation
clang-format -i $(find . -name '*.cpp' -o -name '*.hpp')	Format all source files

---

Examples & Samples

The examples/ directory contains practical demonstrations:

• logger_usage/ - Comprehensive logging examples and best practices
• function_container_usage/ - Event system and callback patterns

Running Examples

# Build a specific example
xmake f --logger_usage=y
xmake build

# Run the example
xmake run LoggerUsage

Each example includes its own README with detailed explanations and use cases.

---

Constraints & Limitations

Technical Constraints

• C++20 Required: Minimum language standard; legacy compilers not supported
• Platform Support: Windows, Linux, macOS (limited testing on macOS)
• Build System: Xmake required; CMake not currently supported
• Threading: Logger is thread-safe via spdlog; function containers are not thread-safe by default

Known Limitations

1. Dependency Management: All dependencies must be available through Xmake package manager
2. Header-Only: Not currently available as header-only library; requires linking
3. Documentation: API documentation requires manual Doxygen generation
4. Examples: Some examples may require additional setup (see individual README files)

Performance Considerations

• Debug Mode: Significant performance overhead due to extensive logging and assertions
• Release Mode: Optimized for production use; minimal overhead
• Memory: Function containers use type-erasure; small overhead per instance

Version Compatibility

• Current Version: 1.0.0
• Stability: Beta - API may change in future releases
• Breaking Changes: Will follow semantic versioning starting from 1.0.0 stable release

---

Coding Style

This project follows the Engine² coding standards enforced via clang-format.

Apply Code Formatting

Bash (Linux/macOS):

find . -iname '*.hpp' -o -iname '*.cpp' | xargs clang-format -i

PowerShell (Windows):

Get-ChildItem -Recurse -Include *.cpp, *.hpp | ForEach-Object { clang-format -i $_.FullName }

---

Documentation

Build Documentation

1. Install Doxygen
2. Generate documentation:

   mkdir -p docs
   doxygen Doxyfile.cfg

3. Open in browser:

   open docs/EngineSquared/html/index.html  # macOS
   xdg-open docs/EngineSquared/html/index.html  # Linux
   start docs/EngineSquared/html/index.html  # Windows

---

Contributing

We welcome contributions! Please read our Contributing Guidelines and Code of Conduct before submitting pull requests.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Apply coding style (clang-format)
4. Write/update tests
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Engine² Main Project: EngineSquared Organization

---

Acknowledgments

• spdlog - Fast C++ logging library by gabime
• fmt - Modern formatting library by Victor Zverovich
• Google Test - Testing framework by Google
• Xmake - Cross-platform build utility by ruki

---

Developed with ❤️ by the Engine² Team @ Epitech