Chronos Package Creator

Chronos is a versatile framework designed to integrate high-performance 2D / 3D content and fluid animations into your app, or to create a game using a comprehensive set of 2D / 3D game-based tools.

The Chronos Package Creator is a development tool used for creating Chronos Packages. To run a Chronos Package that you've developed with the Chronos Package Creator, you need to integrate the Chronos Engine into your app and let the engine run the package you created.

For more information about the Chronos Engine, please refer to the README.md file in the Chronos Engine project.

Getting Started

This tutorial will guide you through the process of creating a Chronos Package. To learn how to integrate the Chronos Engine into your app, please refer to the README.md file in the Chronos Engine project.

Prerequisites

Before you begin, make sure your development environment includes Node.js® and npm, which is installed with Node.js by default.

Node.js

The Chronos Package Creator requires a current, active LTS, or maintenance LTS version of Node.js.

• To download Node.js, visit nodejs.org.
• To check your current version of Node.js, run node -v in a terminal/console window.

Step 1: Create an Empty Directory as Your Workspace

After you've met the prerequisites, create a new directory for your package. This will serve as your workspace. You can do this using a terminal/console window:

mkdir my-package
cd my-package

Before moving on to the next step, make sure that the current working directory is the one you just created by using the cd command.

Step 2: Initialize a package.json File

Packages are developed within an npm workspace. To initialize this workspace, create a package.json file in the directory you created in Step 1.

We recommend using the npm configuration initialization wizard to create a package.json file. Run the npm command-line interface (CLI) command as shown below:

npm init

The npm init command will prompt you for information to include in the initial package. Alternatively, you can manually create a package.json file using the format below:

{
  "name": "my-package",
  "author": "Your Name",
  "description": "a chronos demo package",
  "version": "1.0.0"
}

Your package.json file can contain additional fields, such as license information. However, only the four fields listed above will be added as meta-information to the final published Chronos Package.

Step 3: Install the Chronos Package Creator

The Chronos Package Creator is used to create Chronos Package projects and build the package for the Chronos Engine.

You need to install the Chronos Package Creator using npm. We strongly recommend installing the Chronos Package Creator in the working directory (not globally).

Run the npm CLI command as shown below:

npm install git+https://github.com/chronos-kit/chronos-pkg.git --save-dev

Alternatively, you can install it directly by name from npm registry:

npm install @chronos-kit/chronos-pkg --save-dev

Step 4: Create a chronosrc.json File

Next, you'll need to create a configuration file for the Chronos Package Creator. This file, named chronosrc.json, contains the information necessary for building the package.

We recommend using the Chronos Package Creator's configuration initialization wizard to create the chronosrc.json file. You can do this by running the following command:

node_modules/.bin/chronos-pkg init

The chronos-pkg init command will ask you for the following information to build the package:

• Entry point: A TypeScript file that serves as the entry point of your package.
• Resource directory: A directory containing all resource files.
• Info file: A JSON file that provides meta-information about your package.
• Output file: The location where the final build product file will be saved.

If the file or directory you specify does not exist, the wizard will create it for you.

The structure of your working directory should align with the contents of chronosrc.json. For instance, if your chronosrc.json configuration file looks like this:

{
  "entryPoint": "src/index.ts",
  "resourceDir": "res",
  "infoFile": "info.json",
  "outputFile": "dist/my-package.cron"
}

Then your working directory should have the following structure:

my-package              (root directory of your workspace)
├── src                 (source directory)
│   ├── index.ts        (entry point)
│   ├── foo.ts
│   └── bar.ts
├── res                 (resource directory)
│   ├── logo.png
│   └── bgm.mp3
├── dist
│   └── my-package.cron (output file)
├── node_modules        (dependencies used by npm)
│   ├── @chronos-kit
│   │   └── chronos-pkg (chronos package creator as a dependency)
│   └── ...
├── info.json           (extra package info used by Chronos Package Creator)
├── chronosrc.json      (build options used by Chronos Package Creator)
├── package.json        (package info used by npm)
└── package-lock.json

Step 5: Write the Script Code and Add Resources

The Chronos Package Creator uses TypeScript as its programming language. If you're new to TypeScript, you can refer to the tutorial on the official TypeScript website.

The Chronos Package Creator provides a TypeScript Declaration File for all APIs that can be used in your project. Since chronos-pkg is a Global Library, you can import them into your package using the /// <reference types='@chronos-kit/chronos-pkg' /> directive. For instance:

/// <reference types='@chronos-kit/chronos-pkg' />
cron.log("Hello World!");

If your package requires resource files such as images or sounds, place them in the resource directory specified in Step 4.

For more information about the APIs, refer to the API Overview.

Step 6: Build the Package

Once you've finished coding, you'll need to compile all scripts and package them with the resource files into the specified Chronos Package. The Chronos Package Creator CLI can assist you with this process.

If you wish to include additional meta-information in the package, you can add it to the info file mentioned in Step 4.

Then, run the following Chronos Package Creator CLI command:

node_modules/.bin/chronos-pkg build

Alternatively, you can add this Chronos Package Creator command to your package.json file:

{
  "name": "example",
  "version": "0.1.0",
  "description": "a chronos package example",
  "scripts": {
    "debug-build": "chronos-pkg build --debug",
    "release-build": "chronos-pkg build"
  },
  "devDependencies": {
    "@chronos-kit/chronos-pkg": "git+https://github.com/chronos-kit/chronos-pkg.git" // or "latest"
  }
}

Now, you can build the package using the following CLI command:

npm run release-build

If the build process completes without errors, you can find the package at the output file location specified in Step 4.

Step 7: Run Your Package in the App

You can run your package directly in an app that has already integrated the Chronos Engine.

For instructions on how to integrate the Chronos Engine into your app, and how to run a package using the Chronos Engine, please refer to the README.md file in the Chronos Engine project.

Typically, you can include your package in your app's bundle, or publish it online, and download it dynamically at runtime.

Coding and Debugging

We recommend using Visual Studio Code as a code editor for developing a Chronos Package. With the help of the Chronos Package Creator's declaration file, you will benefit from intelligent code completions and suggestions provided by VS Code when using Chronos TypeScript APIs.

There's an example project in the Chronos Engine's repository that can assist you in testing and debugging your package. See the README.md file in the Chronos Engine project for more details.

If you're debugging with an iOS device, you can directly debug the script you wrote in Safari on your macOS device. Before you start debugging, make sure that your app is signed with an iOS developer certificate and that your iOS device is connected to your macOS device.

Run your app on your iOS device and run Safari on your macOS device. Now, you can find your device, your app, and the corresponding JSContext named Chronos in the Develop menu of Safari to access the debug interface.

To minimize the size of the package, the Chronos Package Creator compiles all TypeScript files into a single JavaScript file and all the names in the script are mangled in the final published package. However, the Chronos Package Creator can output SourceMap data so you can debug directly against the TypeScript code. To do this, simply add the --debug parameter when you build your package:

node_modules/.bin/chronos-pkg build --debug

Alternatively, you can add the debug field in chronosrc.json and set it to true to enable debug mode.

API Overview

Chronos offers a graphics rendering and animation infrastructure that enables you to animate textured images, or sprites, as you wish. Utilizing a rendering loop, Chronos processes the contents of each frame before rendering it. The contents of the scene and their changes in each frame are determined by your package. Chronos efficiently renders frames of animation using the graphics hardware and is optimized to allow arbitrary changes in the positions of sprites in each frame of animation. Additionally, Chronos provides other game-friendly features, including basic sound playback support.

At a Glance

Chronos is compatible with iOS, macOS, and Android. It leverages the graphics hardware of the host device to composite 2D / 3D content at high frame rates. Chronos supports a wide variety of content, including:

• Untextured or textured rectangles (sprites)
• Text
• Arbitrary Bezier-path-based shapes
• Audio

Chronos also offers support for cropping and other special effects, which can be applied to all or a portion of your content. These elements can be animated or altered in each frame.

As Chronos provides a robust rendering infrastructure and handles all the low-level tasks of submitting drawing commands to OpenGL, you can concentrate on addressing higher-level design challenges and creating engaging gameplay.

Content is Rendered by Presenting Scenes

The cron.Window performs animation and rendering.

Your game's content is organized into scenes, represented by cron.Scene objects. A scene contains sprites and other renderable content. It also implements per-frame logic and content processing. At any given time, the cron.Window presents one scene. As long as a scene is presented, its animation and per-frame logic are automatically executed.

To create a game with Chronos, you create scenes and set callback functions to carry out major game-related tasks. For instance, you might create separate scenes to display a main menu, the gameplay screen, and content displayed after the game ends. The cron.Window allows easy switching between different scenes.

For more details, refer to the pages related to cron.Window and cron.Scene in the API Reference.

A Node Tree Determines What Appears in a Scene

The cron.Scene class is a descendant of the cron.Node class. In Chronos, nodes are the fundamental building blocks of all content, with the scene object serving as the root node for a tree of node objects. The scene and its descendants dictate what content is drawn and how it is rendered.

Each node's position is specified in the coordinate system defined by its parent. A node also applies its properties to its content and the content of its descendants. For instance, when a node is rotated, all of its descendants are rotated as well. You can construct a complex image using a tree of nodes and then rotate, scale, and blend the entire image by adjusting the properties of the topmost node.

The cron.Node class does not draw anything, but it applies its properties to its descendants. Each type of drawable content is represented by a distinct subclass in Chronos. Some other node subclasses do not draw content of their own, but modify the behavior of their descendants. For instance, you can use an cron.EffectNode object to apply a shader to an entire subtree in the scene. By carefully controlling the structure of the node tree, you determine the order in which nodes are rendered.

All node objects are responder objects, so you can set callback functions to accept user input. Chronos automatically manages the responder chain of your scene's node tree.

For more details, refer to the pages related to cron.Node and its subclasses in the API Reference.

Textures Store Reusable Graphical Data

Textures are shared images used to render sprites. Always use textures when you need to apply the same image to multiple sprites. Typically, you create textures by loading image files stored in your package. However, Chronos can also create textures for you at runtime from other sources, including binary data or even by rendering a node tree into a texture.

Chronos simplifies texture management by handling the lower-level code needed to load textures and make them available to the graphics hardware. Texture management is automatically handled by Chronos.

For more details, refer to the pages related to cron.Texture in the API Reference.

Nodes Execute Actions to Animate Content

A scene's contents are animated using actions. Every action is an object, defined by the cron.Action class. You instruct nodes to execute actions. Then, when the scene processes frames of animation, the actions are executed. Some actions are completed in a single frame of animation, while others apply changes over multiple frames of animation before completing. Actions are most commonly used to animate changes to the node's properties. For instance, you can create actions that move a node, scale or rotate it, or make it transparent. However, actions can also modify the node tree, play sounds, or even execute custom code.

Actions are highly useful, and can also be combined to create more complex effects. You can create groups of actions that run simultaneously or sequences where actions run sequentially. You can set actions to automatically repeat.

Scenes can also perform custom per-frame processing. You set the callbacks of your scene to perform additional game tasks. For instance, if a node needs to be moved every frame, you might adjust its properties directly every frame instead of using an action to do so.

For more details, refer to the pages related to cron.Action in the API Reference.

API Reference

For a comprehensive API reference, please refer to the index.html file located in the docs directory.