@nixia/2d 0.0.0-stage → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nixia.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# 🎮 NIXIA 2D Game Engine
+> A lightning-fast, lightweight 2D game engine written entirely in TypeScript, engineered from the ground up to run seamlessly on low-power machines and resource-constrained devices.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+---
+
+## 🚀 Getting Started
+
+Getting your first Nixia project up and running takes less than a minute. Follow these simple steps:
+
+### 1. Initialize your workspace
+Create a new directory for your game and step into it:
+```bash
+mkdir my-game
+cd my-game
+```
+
+### 2. Install the core package
+Install the NIXIA package as a development dependency (this automatically pulls in Vite and all other required toolchain dependencies):
+```bash
+npm install -D @nixia/2d
+```
+
+### 3. Initialize your project structure
+Run the built-in CLI tool to scaffold your configuration files and entry point:
+```bash
+nixia init
+```
+
+Once initialization is complete, you are ready to write code! Your application's main entry point is located at `src/main.ts`
+
+## 🏗️ Creating Your First Level
+Levels represent the scenes or stages of your game. To create a new level, generate a new TypeScript file inside `src/levels/MyLevel.ts`, extend the core `Nixia.Level` class, and configure it:
+
+```ts
+// src/levels/MyLevel.ts
+import * as Nixia from '@nixia/2d';
+
+export class MyLevel extends Nixia.Level {
+  constructor() {
+    super("MyLevel");
+  }
+}
+```
+
+Then in your `src/main.ts`, you can make this your default level by using the following code:
+```ts
+// src/main.ts
+import * as Nixia from '@nixia/2d';
+import { MyLevel } from './levels/MyLevel';
+
+// Preload your level
+const myLevel = new MyLevel();
+
+// Create a new Application
+const app = new Nixia.Application();
+
+// Set the default level to our custom level
+app.setDefaultLevel(myLevel);
+
+// Start the application
+app.start();
+```
+
+## 👾 Creating Your First Actor
+Actors represent game objects—or more specifically, active entities living inside a level. They handle components, custom game logic, rendering, physics, and more. You can create one like this:
+
+```ts
+// src/actors/MyActor.ts
+import * as Nixia from '@nixia/2d';
+
+export class MyActor extends Nixai.Actor {
+  constructor() {
+    super("MyActor");
+  }
+}
+```
+
+You can add your Actor to your Level like this:
+```ts
+// src/levels/MyLevel.ts
+import * as Nixia from '@nixia/2d';
+import { MyActor } from './actors/MyActor';
+
+export class MyLevel extends Nixia.Level {
+  constructor() {
+    super("MyLevel");
+
+    // This both adds the actor to the scene and registers it with
+    // the game lifecycle.
+    this.root.add(new MyActor(this, this.app));
+  }
+}

package/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function runCli() {
+    console.log('🔍 Running pre-flight environment checks...');
+
+    // Centralized pre-flight checks to prevent accidental overwrites
+    const existenceChecks = [
+        { target: "src", message: "Error: The 'src/' directory already exists. Aborting to protect your files." },
+        { target: "tsconfig.json", message: "Error: 'tsconfig.json' already exists in this directory." },
+        { target: "vite.config.ts", message: "Error: 'vite.config.ts' already exists in this directory." }
+    ];
+
+    for (const check of existenceChecks) {
+        if (fs.existsSync(check.target)) {
+            throw new Error(check.message);
+        }
+    }
+    console.log('✅ Pre-flight checks passed successfully!');
+
+    console.log('💾 Creating project structure and writing files locally...');
+    
+    // Ensure the src directory exists before writing nested files
+    fs.mkdirSync("src", { recursive: true });
+
+    // 1. Write index.html
+    const indexHtmlContent = `<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Nixia Engine Default Game</title>
+    </head>
+    <body>
+        <script type="module" src="./src/main.ts"></script>
+    </body>
+</html>`;
+    fs.writeFileSync("index.html", indexHtmlContent);
+    console.log('📄 Created index.html successfully!');
+
+    // 2. Write tsconfig.json (Fixed the missing filename bug!)
+    const tsConfigData = {
+        "compilerOptions": {
+            "target": "ESNext",
+            "useDefineForClassFields": true,
+            "module": "ESNext",
+            "moduleResolution": "bundler",
+            "isolatedModules": true,
+            "strict": true,
+            "noUnusedLocals": true,
+            "noUnusedParameters": true,
+            "noImplicitReturns": true,
+            "skipLibCheck": true,
+            "resolveJsonModule": true,
+            "esModuleInterop": true,
+            "allowSyntheticDefaultImports": true,
+            "types": ["vite/client"]
+        },
+        "include": ["src/**/*", "vite.config.ts"]
+    };
+    fs.writeFileSync("tsconfig.json", JSON.stringify(tsConfigData, null, 2));
+    console.log('📄 Created tsconfig.json successfully!');
+
+    // 3. Write vite.config.ts
+    const viteConfigContent = `import { defineConfig } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+export default defineConfig({
+    plugins: [viteSingleFile()],
+    build: {
+        target: 'esnext',
+        assetsInlineLimit: 100000000,
+        chunkSizeWarningLimit: 100000000,
+        cssCodeSplit: false,
+        rollupOptions: {
+            output: {
+                inlineDynamicImports: true,
+            },
+        },
+    },
+});`;
+    fs.writeFileSync("vite.config.ts", viteConfigContent);
+    console.log('📄 Created vite.config.ts successfully!');
+
+    // 4. Write src/main.ts
+    const mainTsContent = `// This is the entry point for your game.
+import * as Nixia from '@nixia/2d';
+
+// Hello, world!`;
+    fs.writeFileSync(path.join("src", "main.ts"), mainTsContent);
+    console.log('📄 Created src/main.ts successfully!');
+
+    console.log('✅ All project components written to disk successfully!');
+
+    console.log('📦 Updating package.json configuration...');
+    const packageJsonPath = path.join("package.json");
+    
+    if (fs.existsSync(packageJsonPath)) {
+        const packageData = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        
+        // Safely inject scripts and type module setting
+        packageData.scripts = {
+            ...(packageData.scripts || {}),
+            "dev": "vite",
+            "build": "vite build",
+            "preview": "vite preview"
+        };
+        packageData.type = "module";
+
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageData, null, 2));
+        console.log('✨ package.json updated successfully with Vite scripts and ESM type!');
+    } else {
+        console.warn('⚠️ Warning: package.json not found in the current directory. Skipping script injection.');
+    }
+
+    console.log('🎉 Project scaffolding completed successfully! Happy coding! 🚀✨');
+}
+
+// Global execution wrapper with robust error catching
+runCli().catch((error) => {
+    console.error(`\n💥 Fatal CLI Error: ${error.message}`);
+    process.exit(1);
+});

package/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Nixia Engine Default Game</title>
+    </head>
+    <body>
+        <script type="module" src="./src/main.ts"></script>
+    </body>
+</html>

package/package.json

@@ -1,6 +1,35 @@
 {
-  "name": "@nixia/2d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@nixia/2d",
+    "version": "0.0.3",
+    "author": {
+        "name": "Aedan Maki",
+        "email": "aedanmaki@gmail.com"
+    },
+    "bin": "./cli.js",
+    "license": "MIT",
+    "type": "module",
+    "main": "./src/index.ts",
+    "module": "./src/index.ts",
+    "keywords": ["game-engine", "2d"],
+    "exports": {
+        ".": {
+            "import": "./src/index.ts",
+            "types": "./src/index.ts"
+        }
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview",
+        "publish": "nixia publish"
+    },
+    "devDependencies": {
+        "fs": "^0.0.1-security",
+        "path": "^0.12.7"
+    },
+    "dependencies": {
+        "typescript": "^7.0.2",
+        "vite": "^8.3.5",
+        "vite-plugin-singlefile": "^2.3.4"
+    }
+}

package/src/core/Actor.ts

@@ -0,0 +1,20 @@
+// src/core/Actor.ts
+import { Base } from "./Base";
+import { ITickable } from "./ITickable";
+
+/**
+ * Represents an Actor.
+ */
+export class Actor extends Base implements ITickable {
+    /**
+     * Creates a new Actor.
+     */
+    constructor() {
+        super();
+    }
+
+    /**
+     * Called on tick.
+     */
+    tick(dt: number): void {}
+}

package/src/core/Application.ts

@@ -0,0 +1,105 @@
+// src/core/Application.ts
+import { Base } from "./Base";
+import { ITickable } from "./ITickable";
+import { Renderer } from "./Renderer";
+import { Level } from "./Level";
+
+/**
+ * Represents an Application.
+ */
+export class Application extends Base {
+    /**
+     * If the game has already been initialized.
+     */
+    private wasInitialized: boolean = false;
+
+    /**
+     * If the game is ready.
+     */
+    private isReady: boolean = false; 
+
+    /**
+     * Previous tick time.
+     */
+    private previousTickTime: number = Date.now();
+
+    /**
+     * An array of every tickable instance.
+     */
+    private tickableInstances: ITickable[] = [];
+
+    /**
+     * The renderer instance.
+     */
+    private renderer: Renderer;
+
+    /**
+     * The default level.
+     */
+    private defaultLevel!: Level;
+
+    /**
+     * Creates a new Application.
+     */
+    constructor() {
+        super();
+
+        this.renderer = new Renderer();
+    }
+
+    /**
+     * Starts the Application.
+     */
+    start() {
+        if (this.wasInitialized) throw new Error('Application is already initialized.');
+        this.wasInitialized = true;
+
+        if (document.readyState === 'complete') {
+            this._ready();
+        } else {
+            window.addEventListener('load', () => {
+                this._ready();
+            });
+        }
+    }
+
+    /**
+     * Called when the game is ready.
+     */
+    private _ready() {
+        this.isReady = true;
+        if (!this.defaultLevel) throw new Error("No default level was assigned, cannot create game.");
+        this.fire('ready');
+
+        requestAnimationFrame(this._tick);
+    }
+
+    /**
+     * Called on tick.
+     */
+    private _tick = () => {
+        const now = Date.now();
+        const delta = now - this.previousTickTime;
+
+        const len = this.tickableInstances.length;
+        for (let i = 0; i < len; i++) {
+            const inst = this.tickableInstances[i];
+            inst.tick(delta);
+        }
+
+        this.renderer.clear();
+        this.renderer.draw();
+
+        this.previousTickTime = now;
+
+        requestAnimationFrame(this._tick);
+    }
+
+    /**
+     * Sets the default level.
+     */
+    setDefaultLevel(defaultLevel: Level) {
+        if (this.isReady) throw new Error("Cannot assign a default level when the game is already running.");
+        this.defaultLevel = defaultLevel;
+    }
+}

package/src/core/Base.ts

@@ -0,0 +1,25 @@
+// src/core/Base.ts
+
+/**
+ * Base class containing code for replication and events.
+ */
+export abstract class Base {
+    private events: Map<string, Function[]> = new Map();
+
+    on(event: string, callback: Function) {
+        const callbacks = this.events.get(event);
+        if (!callbacks) this.events.set(event, [callback]); else {
+            callbacks.push(callback);
+            this.events.set(event, callbacks);
+        }
+    }
+
+    fire(event: string) {
+        const callbacks = this.events.get(event);
+        if (!callbacks) return;
+        const len = callbacks.length;
+        for (let i = 0; i < len; i++) {
+            callbacks[i]();
+        }
+    }
+}

package/src/core/ITickable.ts

@@ -0,0 +1,5 @@
+// src/core/ITickable.ts
+
+export interface ITickable {
+    tick(dt: number): void;
+}

package/src/core/Level.ts

@@ -0,0 +1,27 @@
+// src/core/Level.ts
+import { Base } from "./Base";
+import { ITickable } from "./ITickable";
+
+/**
+ * Represents a Level.
+ */
+export class Level extends Base implements ITickable {
+    /**
+     * The level name.
+     */
+    private name: string;
+
+    /**
+     * Creates a new Level.
+     */
+    constructor(name: string) {
+        super();
+
+        this.name = name;
+    }
+
+    /**
+     * Called on tick.
+     */
+    tick(dt: number): void {}
+}

package/src/core/RenderBuffer.ts

@@ -0,0 +1,13 @@
+// src/core/RenderBuffer.ts
+
+/**
+ * Represents a Render Buffer.
+ */
+export class RenderBuffer {
+    /**
+     * Creates a new Render Buffer.
+     */
+    constructor() {
+
+    }
+}

package/src/core/Renderer.ts

@@ -0,0 +1,40 @@
+// src/core/Renderer.ts
+import { Base } from "./Base";
+
+/**
+ * Represents a Renderer.
+ */
+export class Renderer extends Base {
+    /**
+     * The canvas element.
+     */
+    private canvas: HTMLCanvasElement;
+
+    /**
+     * Creates a new Renderer.
+     */
+    constructor() {
+        super();
+
+        const canvas = document.createElement("canvas") as HTMLCanvasElement;
+        this.canvas = canvas;
+        this.canvas.width = 600;
+        this.canvas.height = 400;
+        this.canvas.style.border = "1px solid black";
+        document.body.appendChild(this.canvas);
+    }
+
+    /**
+     * Completely clears the canvas.
+     */
+    clear() {
+        
+    }
+
+    /**
+     * Draws the buffers onto the canvas.
+     */
+    draw() {
+
+    }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// src/index.ts
+
+export * from './core/Actor';
+export * from './core/Application';
+export * from './core/Base';
+export * from './core/ITickable';
+export * from './core/Level';
+export * from './core/RenderBuffer';
+export * from './core/Renderer';

package/src/main.ts

@@ -0,0 +1,8 @@
+import * as Nixia from './index';
+import { MyLevel } from './test/MyLevel';
+
+const app = new Nixia.Application();
+
+app.setDefaultLevel(new MyLevel());
+
+app.start();

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*", "vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+export default defineConfig({
+    plugins: [viteSingleFile()],
+    build: {
+        target: 'esnext',
+        assetsInlineLimit: 100000000,
+        chunkSizeWarningLimit: 100000000,
+        cssCodeSplit: false,
+        rollupOptions: {
+            output: {
+                inlineDynamicImports: true,
+            },
+        },
+    },
+});