A webgl based game engine.
Caldro is a HTML5 based game engine that utilizes the WebGL rendering API for its graphical output. The project was first initiated by Vachila and Bytenol in early 2021. It started off as a canvas2d based API until mid-2024 when webgl got introduced as the default renderer.
Caldro must be initialized before doing anything and the initialization process
must be done after the document has been loaded. Preferrably, inside a window.onload
event.
// this import uses a relative path, your's might be different
import * as Caldro from "./build/src/core/Caldro.js";
// do this within a scene.onload event
const initParams = {
parent: document.body,
scene: null,
// optional parameters and their options
renderer: "webgl2", // 'webgl'
physics: null, // box2d, matter, default
orientation: "portrait" // 'landscape'
}
// is there anything that goes wrong, lets find out
if (!Caldro.init(params)) throw new Error(Caldro.getError());
// or just start the engine
Caldro.start();
The parent attribute is important though it can be any of the HTMLDivElement in your document. scene is something to talk about in the next stage. renderer can only be a string of "webgl" or "webgl2". If your game uses any physics engine, The name should be provided as commented in the code. The physics engine must be either "box2d", "matter" or "default". orientation describes the alignment of the parent element as portrait or landscape.
it is pertinent to know that the function Caldro.getError()
hold the current error
message as a string. This can be handy in debugging lots of internal issues.
Caldro.init() - May throw an instance of CanvasCreationError
, GLCreationError
.
Well, if you have none of the above error in the console, the implementation
expect that you have an error that says An instance of a scene must be created for default caldro...
.
This error is expected since the Caldro engine expect to have atleast one scene to be available.
The next lesson will talk about how to fix this issue.
A Caldro scene is a javascript class that can represent a whole page or part of a page.
The scene inherited from the Node class just like every other components. To create a scene like
object, you must extends from Scene
(An Abstract class).
class SimpleScene extends Scene {
constructor() {
super(null);
this.w = 400; // width of the scene
this.h = 400; // height of the scene
}
}
The next thing is to create an instance of a SimpleScene
and attach it to the game configuration.
const initParams = {
//...
scene: new SimpleScene(),
//...
}
The scene constructor takes as argument the parent node. By default, A scene will take the size of its parent node except if explicitly stated anywhere in the scene lifecycle. The lifecycle of a scene include the methods
onCreate(gl: WebGLRenderingContext): boolean
called immediately after the constructor. This is where initialization should take placeonUpdate(timeStamp: number): boolean
: This is where the game logic should take place. This method is called repeatedly before the draw methodonDraw(gl: WebGLRenderingContext): boolean
. This is where continuos drawing should take place. This method is called repeatedly after the onUpdate methodonExit(gl: WebGLRenderingContext): boolean
. Called when the scene is about to exit.
We can further our scene by making the background blue
class SimpleScene extends Scene {
// ...constructor
onUpdate(gl) {
// setting the viewport
this.setRenderViewport(0, 0, 100, 100);
// setting the clear color. A number between 0-1
this.setRenderClearColor(0x0, 0x0, 0x1, 0x1);
// clearing the renderer
this.renderClear();
return true; // ITS IMPORTANT
}
}
Now, we should see a blue background scene. Yay.
One of the most easiest thing to get started with is shapes. Caldro provide the following set of geometrical shapes. The two most basic shapes provided are Rectangle, Cirlce and Polygon... plus, ermm... lines
More content on this later
Open Source: More content on this later