Chronos

Seize The Day

pre-alpha

       

   

     

Note

Following the acquisition of GitHub by Micro$lop, we have taken principled action and have begun primarily hosting code and content on Codeberg. Mirrors will still be maintained on GitHub and GitLab.

A Customizable, data-driven, in-game, multiplayer Calendar, Time and Event System. Sequence Environmental Appearance, Curve Data and Events over a Day or any period.

Chronos is a part of the Target Vector framework.

🌐Site • 📚Wiki • 📘Documentation • 📑Chronos Notion • 🐤Twitter • 🗨️Discord

Introduction

Immerse the player in your games lore-accurate calendar and time system. From a Blistering Midday Sun to a Stormy Winter Evening; Drive engrossing Environmental details with your story.

Features

Warning

Chronos is under heavy development, including a rewrite to utilze GAS, Modular features and new technologies. Many features may not be finished or production-ready. Use at your own risk.

• Calendar Asset - Define x Months per Year, y Days per Month 1 Week 1, z Days per Month 1 Week 2...
• DayTime Asset - Define x Hours per day, y Minutes per Hour, z Seconds per Minute.
• Define different DaySequences for any number of yearly Phases (ie Seasons).
• Data Asset-oriented - Save Calendars and Day structures as Data Assets.
• Map Curves to Calendars - For use in Temparature Ranges (Vector), Average Humidity (Float) etc.
• Time Scale/Time Dilation
• Trigger Events at Specific Times, at a Percentage of a Time Range, on a New Day/Week/Month/Year etc.
• Write Data to a Material Parameter Collection.

Tools

• Automated Test sample(s).
• Workflows for Forgejo. Codeberg, Github and Gitlab.
• Scripts for Convenience, CI and Automation.

Goals

• Provide a Customizable, Multiplayer Date Time System.
• Provide a Robust, Data-Oriented Event System.
• Encourage and facilitate adoption of Continuous Integration and Continuous Delivery (CI/CD) practices and Test Driven Development (TDD).
• Adhere to, promote and facilitate adherance to the Epic C++ Coding Standards for Unreal Engine and Gamemakin UE5 Style Guide

Organizational Ethos

System Requirements

• Unreal Engine 5.7 or later
• Windows 10 (or later) or Linux (Tested on Debian).

Dependencies

Engine Plugins

The following are built-in Engine plugins that are enabled in the Plugins window. Note: some Plugins may be Experimental or Beta software.

• DaySequence

Installation

Fab Plugin Installation

Not available on Fab. Please perform Manual Installation

Manual Installation

Latest Release

No Releases yet. Plesae Compile From Source Code

1. Install and setup all Dependencies (if required).
2. Download Latest Release from Releases.
3. Unzip to your project Plugins folder.
4. (Re)Start Unreal Engine Editor.

Compile From Source Code

Your host machine must fulfill additional System Requirements to compile this project from source.

Compiliation System Requirements

• A working UE5 C++ Integrated Developement Environment(IDE)
  • Tested: Jetbrains Rider, VS Code, Visual Studio (Windows)
  • Untested: XCode (MacOS), Jetbrains Rider, VS Code, Visual Studio (Linux)
• clang -20 13.0.1

Quick Installation

1. Install and setup all Compiliation System Requirements.
2. Install and setup all Dependencies (if required).
3. Clone/download Chronos into your projects Plugin folder.
4. (Re)Build Plugin with the BuildPlugin.bat Script or (Re)Build Project normally with your IDE.
5. Once compilation is successful you can now begin using Chronos in your project

View All Available Scripts

Full Installation

Full Installation Instructions are available in the Chronos Wiki

Getting Started

To view a working demonstration, load and play the L_Chronos level in the /Levels folder. The Demo Widget will allow you to adjust parameters in Realtime.

To integrate Chronos into a new or existing Game State, some setup is required:

1. Add ChronosGameStateComponent to your Game State.
2. Add ChronosGameStateInterface to your Game State.
3. Implement ChronosGameStateInterface functions in your Game State.
4. Configure ChronosGameStateComponent.

The full Getting Started guide is available in the Chronos Wiki

Content Overview

(root)/                                # Demo Game Mode and Game State
├──Components/ 
    ├── ChronosGameStateComponent      # Game State Component.
├──Interfaces/ 
    ├── ChronosGameStateInterface      # Game State Interface.
├──Data/                               
    ├── Calendar                       # Sample Calendar Data Assets.
    ├── DayTime                        # Sample DayTime Data Assets.
    ├── Curves                         # Sample Data Curves.
    ├── MPC                            # Material Parameter Collection.
├──Characters/                         # Demo ChronosCharacter Class.
    ├── Input                          # ChronosCharacter Input.
├──Levels/                             # Demo Level(s).

Chronos Game State Component

Manages the replicated progression of Time and the Calendar, launches bound Events and outputs data.

Chronos Game State Interface

Provides easy access to Chronos data from anywhere the Game State is available.

Material Parameter Collection

The ChronosGameStateComponent can be configured to write Parameters to a Material Parameter Collection for use in Materials.

Settings

For detailed descriptions all Settings, please consult the Chronos Wiki or the Chronos Documentation.

CI

To encourage and facilitate the adoption of CI, this project is preconfigured for CI with the Workflows and Scripts below.

CI System Requirements

Systems performing Continous Intergration Workflows will have additional requirements depending on the CI solution used.

• Git
• OpenCppCoverage
• Domain Name or ngrok (For Self Hosted CI)
• Workflow Actions services and Runners configured for Forgejo/Codeberg, GitHub or GitLab
• Jenkins and Java 11 (For Jenkins)

Workflows

CI workflow YAML files are included for Forgejo/Codeberg, GitHub and GitLab and feature Cross-compilation to target both Windows and Linux from a Windows host.

ue-plugin-ci Build, Test, Code Coverage, Upload to Codecov, Update Changelog, Update Status. Activated with any push. ue-plugin-ci-release Build, Cook, Package, Test, Code Coverage, Upload to Codecov, Update Changelog, Update Status. Activated the a v* tag in the commit. changelog Generates and commits CHANGELOG.md. Activated the a v* tag in the commit. doxygen-remote-repo Generates doxygen Documentation. Activated the a v* tag in the commit. greetings Welcomes new contributors.

Available Scripts

Batch(Windows) and Shell(Linux) scripts are included for convenience and automation.

• ./BuildPlugin.bat - Build Plugin Batch Script
• ./BuildPlugin.sh - Build Plugin Shell Script
• ./RunAutomatedTests.bat - Run Automated Tests Batch Script
• ./RunAutomatedTests.sh - Run Automated Tests Shell Script

Automated Testing

The provided tests can be run in an Action Workflow or run manually with RunUAT. Learn more about Unreal Engine Automated Testing in the Run Automated Tests documentation.

• ChronosTest

Code Coverage

OpenCodeCoverage will perform Code Coverage analysis and publish an XML file as a Commit Artifact, which can optionally be uploaded to a configured Codecov account. You will need to first generate an Access Token from your Codecov account and add it your Forgejo/Codeberg, GitHub or GitLab Secrets as CODECOV_TOKEN.

Contributions

Contibutors and PRs are very welcome! If you wish to contribute, please follow CONTRIBUTING to get started.

License

This project is dual-licensed. It is available for absoultely free under the MIT License for most Individuals and Organizations. If your organization, industry or application is listed in the Commercial License, please Contact Us.

Any git submodules are covered by their respective licenses. Content listed in the Attributions are covered by their respective licenses.

Attributions

Please view ATTRIBUTIONS

Special Thanks