kenzo-graphics-library-v2
Version:
Lightweight 2D/3D JavaScript engine using HTML5 canvas, math-based and fast.
358 lines (251 loc) • 8.8 kB
Markdown
# Kenzo Graphics Library v2 (KGL)
Kenzo Graphics Library (KGL) is a lightweight, math-based 2D and 3D engine for web-based applications and games. Designed for speed, simplicity, and small-scale use, KGL enables fast prototyping and educational graphics applications in HTML environments without external dependencies.
## Key Features
* 2D and 3D rendering via `<canvas>`
* UI elements (buttons, modals, images, etc.)
* Texturing, shading, and lighting simulation
* Built-in input handling for mouse and keyboard
* HTML/HTA integration support via HTSTB system
## Getting Started
### HTML Setup
```html
<canvas id="myCanvas" width="640" height="480"></canvas>
<script src="kgl.js"></script>
<script>
const canvas = document.getElementById('myCanvas');
const kgl = new Kgl(canvas);
function animate() {
kgl.clear();
kgl.updateRotation();
kgl.drawSolid(vertices, faces);
requestAnimationFrame(animate);
}
animate();
</script>
```
### HTA Usage (Windows Desktop App Style)
```html
<!DOCTYPE html>
<hta:application>
<html>
<body>
<canvas id="c" width="640" height="480"></canvas>
<script src="kgl.js"></script>
<script>
const canvas = document.getElementById('c');
const kgl = new Kgl(canvas);
const ui = new KglUI(kgl);
const htmlBox = new KglHTSTB(canvas);
htmlBox.createBox(10, 10, 200, 100, "<b>Hello from HTA</b>");
</script>
</body>
</html>
```
### Scene Example
```js
const scenes = new KGLscenes();
scenes.add('main', () => {
voxel.drawVisibleChunks({ x: 0, y: 0, z: 0 });
});
function animate() {
kgl.clear();
scenes.render('main');
requestAnimationFrame(animate);
}
animate();
```
### Entity Example
```js
const player = new KGLentity(0, 0, 0, '#3cf');
function gameLoop() {
player.z += 0.1;
player.render(kgl);
requestAnimationFrame(gameLoop);
}
gameLoop();
```
## New Modules
### `KGLvoxel`
* **Voxel-based chunk system** with support for dynamic voxel addition/removal.
* Optimized chunk-based rendering.
* Supports draw distance filtering.
### `KGLentity`
* Simplified way to define and move basic 3D objects.
* Includes update and render methods.
* Great for players, enemies, objects.
### `KGLscenes`
* Manage separate scenes for menus, gameplay, overlays.
* Switch between scene names and call `render(name)`.
* Keeps game logic and rendering modular.
### `KGLconsole`
* Color the Node.js console
### Usage
```js
import { KGLconsole } from './kgl.js';
KGLconsole.print.color("red", "This is a red message");
KGLconsole.print.color("gray", "This is a gray message");
KGLconsole.print.info("This is an info message");
KGLconsole.print.warn("Warning: Something might be wrong");
KGLconsole.print.error("Error: Something went wrong!");
KGLconsole.print.success("Operation successful!");
```
**Note: This does NOT support BG colors, If you want to use BG and FG please use KACP (Kenzo ANSI color printing)**
## 📡 KGLhttp – Basic HTTP Requests (Fetch Wrapper)
`KGLhttp` provides a simple interface for making HTTP requests in KGL-based projects. It allows you to perform basic GET and POST requests using JavaScript's native `fetch()` with added error handling.
### Usage
```js
import { KGLhttp } from './kgl.js';
KGLhttp.get('https://api.example.com/data')
.then(response => console.log(response))
.catch(err => console.error('GET failed:', err));
KGLhttp.post('https://api.example.com/send', { name: 'Kenzo' })
.then(response => console.log('Sent:', response))
.catch(err => console.error('POST failed:', err));
```
### Features
* `.get(url)` – Performs a GET request and returns a promise.
* `.post(url, data)` – Sends data as JSON via POST and returns a promise.
* Graceful error catching for network failures.
## 🌐 KGLnoise – Procedural Noise Generator
`KGLnoise` allows generation of noise-based values for procedural terrain, visual effects, and animation.
### Noise Types
* `perlin(x, y)` – Generates smooth Perlin noise.
* `normal(x, y)` – Standard random-based noise.
* `kenzo(x, y)` – Hybrid custom noise (mix of Perlin + random for sharper terrain edges).
### Usage
```js
import { KGLnoise } from './kgl.js';
const noise = new KGLnoise();
let val = noise.perlin(12.3, 45.6); // Smooth terrain
let grain = noise.normal(32, 11); // Static noise
let hybrid = noise.kenzo(8.7, 1.2); // Mixed style
```
### Use Cases
* Flat terrain generators
* Particle jitter
* Animated waves / clouds
* Procedural 2D textures
### 🧪 Example: Using KGLnoise for Terrain Heightmap
```js
const noise = new KGLnoise();
for (let x = 0; x < 100; x++) {
for (let y = 0; y < 100; y++) {
let height = noise.kenzo(x / 20, y / 20) * 50;
kgl2d.drawRect(x * 5, y * 5, 5, 5, true);
}
}
```
## Best Practices for Lightweight Games
* **Minimize Faces:** Use low-poly models for 3D.
* **Reuse Buffers:** Avoid regenerating geometry or textures each frame.
* **Limit Draw Calls:** Batch rendering where possible.
* **Turn Off What You Don’t Use:** Use `KGLconfig.Disable3D` or `Disable2D` when appropriate.
* **Optimize Loops:** Keep animations and calculations efficient.
# 🧩 KGML – Kenzo Game Mod Loader
**KGML** (Kenzo Game Mod Loader) is a lightweight JavaScript-based loader for adding and managing mods in games or web-based environments. It's part of the Kenzo Graphics Library ecosystem and provides simple APIs to register, initialize, and destroy mods cleanly.
## 📦 Features
* ✅ Register mods with `init` and `destroy` functions
* 🔁 Automatically initialize all registered mods
* ❌ Cleanly destroy all mods when needed
* 🧼 Built-in safety checks for invalid mod formats
* ⚡ Lightweight and dependency-free
## 🚀 Getting Started in KGML
### 1. Include KGML
```js
import { KGML } from './kgl.js';
// Or use a CDN
```
### 2. Register Mods
```js
const kgml = new KGML();
kgml.registerMod("MyMod", {
init() {
console.log("✅ MyMod initialized!");
},
destroy() {
console.log("❌ MyMod destroyed.");
}
});
```
### 3. Initialize All Mods
```js
kgml.initAll();
```
### 4. Destroy All Mods
```js
kgml.destroyAll();
```
## 🧪 Example
```js
const kgml = new KGML();
kgml.registerMod("ExampleMod", {
init() {
console.log("🎮 ExampleMod is running!");
},
destroy() {
console.log("💥 ExampleMod shut down.");
}
});
kgml.initAll(); // Output: 🎮 ExampleMod is running!
kgml.destroyAll(); // Output: 💥 ExampleMod shut down.
```
## ❗ Notes
* Mods **must** have both `init()` and `destroy()` methods.
* Mods with duplicate names will be rejected.
* This tool is meant for in-browser or engine-mod systems (like Kenzo Engine or KGL).
## Debugging Guide
### Common Errors
* **Face Culling in 2D**
* Error: `KGL error : 500 (Face culling is not for 2D)`
* Fix: Set `KGLconfig.UseFaceCulling = false` before initializing a `Kgl2D` instance.
* **Canvas Tainted by Cross-Origin Texture**
* Warning: `KGL warning: Canvas tainted...`
* Fix: Load textures from same origin or ensure CORS is configured correctly.
* **Disabled Components Not Loading**
* If `KGLconfig.Disable2D = true`, `Kgl2D` will not initialize.
* Fix: Ensure correct config flags are set before using components.
### Tips
* Use `KGLconfig.IsInDev = true` to enable dev-mode behavior.
* Call `KGLconfig.info()` to print current configuration.
* Use browser devtools to set breakpoints in animation loops.
## Configuration
Set flags before creating components:
```js
KGLconfig.set({
AppName: "My Mini Game",
UseFaceCulling: true,
Disable2D: false,
DisableHTSTB: false
});
```
## Examples
* **Voxel sandbox games**
* **Scene-based 3D interfaces**
* **3D Cube with UI**
* **2D Platformer Prototype**
* **HTA Tool with Canvas Buttons and Info Panels**
Explore the `KglUI`, `Kgl2D`, and `KglHTSTB` classes for ready-made UI and layout tools.
## Final Notes
KGL is ideal for indie experiments, educational demos, and rapid prototyping. While it's not intended for complex or physics-heavy projects, it remains highly extensible for creative and compact visual interfaces.
Happy coding!
# CDN/LINKS
[JSdelivr](https://cdn.jsdelivr.net/gh/KenzoBasarTheDev/KGL.js/kgl.js)
[NPM](https://www.npmjs.com/package/kenzo-graphics-library-v2)
## License
Kenzo Graphics Library v2 is licensed under the [GPL 3.0 License](https://www.gnu.org/licenses/gpl-3.0.en.html).