repository·main·Indexed 19 days ago
https://github.com/achtaitaipai/odycA lightweight JavaScript library for creating narrative-driven games using code. Odyc.js allows developers to integrate pixels, sound, text, and logic within a single file. Key features include a canvas-based dialog system with typing animations, a camera system for viewport management, and a unified game state for managing players, maps, and turns.
The apps/examples package is organized as follows:
games/: Contains the HTML entry points for each individual example application.src/: Contains the TypeScript source files for the examples.index.html: The main landing page that indexes all available examples.To start the development environment for the Odyc examples, run the following command from the apps/examples directory. This will launch the local development server so you can view and interact with the example applications.
npm run devYou can initialize a new game instance by importing createGame from the odyc package and passing a configuration object to it.
import { createGame } from 'odyc'
const game = createGame({
// Configuration options go here
})To use the odyc library in your project, install the odyc package using npm.
npm install odycYou can scaffold a new example application using the built-in generator. This command automatically creates the necessary file structure and updates the main index page so the new example is discoverable in the examples list.
npm run create-example my-game-nameWhen working with the game engine, use the following types for spatial and content representation:
Tile: A string or number representing the content of a single cell.Position: A tuple of two numbers [number, number] representing [x, y] coordinates.export type Tile = string | number
export type Position = [number, number]onTurn callback, the player is passed as a facade. The facade is a restricted interface that allows you to read and write the player's sprite, position, direction, and visible properties without exposing the full internal Player instance logic.The CameraParams type defines the configuration required to initialize a Camera instance. It requires screen dimensions and the game map, while allowing optional constraints for the camera's viewable area.
Required Properties:
screenWidth: The width of the renderer's screen.screenHeight: The height of the renderer's screen.map: The map data from GameStateParams.Optional Properties:
cameraWidth: A constraint on the camera's width.cameraHeight: A constraint on the camera's height.If both cameraWidth and cameraHeight are provided, the camera uses a centered rectangle (#rect) to calculate positioning logic.
import { CameraParams } from './packages/odyc/src/camera.js';
const params: CameraParams = {
screenWidth: 800,
screenHeight: 600,
map: myMapData,
cameraWidth: 400, // Optional
cameraHeight: 300 // Optional
};To initialize a MessageBox, you must provide a MessageBoxParams object. This object defines the visual styling for the message box background and text content, using either a color index (number) or a CSS color string. It also requires a colors object from RendererParams to resolve these values.
Properties:
messageBackground: The background color for the message box (string or number).messageColor: The text color for the message content (string or number).colors: The color palette used for resolving color indices (RendererParams['colors']).import { MessageBoxParams } from './messageBox';
import { RendererParams } from './renderer';
const params: MessageBoxParams = {
messageBackground: '#000000',
messageColor: 1,
colors: { /* ... RendererParams['colors'] ... */ }
};The DialogParams object defines the visual appearance and typing behavior of the dialog box. It requires color definitions for the background, text, and border, as well as a typing speed setting.
Properties:
dialogBackground: Background color for the dialog box. Can be a color index (number) or a CSS color string.dialogColor: Text color for the dialog content. Can be a color index (number) or a CSS color string.dialogBorder: Border color for the dialog box outline. Can be a color index (number) or a CSS color string.dialogSpeed: The typing animation speed. Must be one of the keys from the internal DIALOG_SPEED mapping: 'SLOW', 'NORMAL', or 'FAST'.colors: An object of type RendererParams['colors'] used to resolve color indices into actual colors.const params: DialogParams = {
dialogBackground: '#000000',
dialogColor: '#ffffff',
dialogBorder: '#ff0000',
dialogSpeed: 'NORMAL',
colors: { /* ... RendererParams colors ... */ }
};The Config<T> type defines the complete configuration for an Odyc.js game. It is a composite type that merges parameters for the renderer, input handler, sound player, camera, message box, dialog system, and game state. All properties are optional and will fall back to defaultConfig if omitted.
Key configuration areas include:
map and a templates object to map characters to behaviors and sprites.colors (an array of hex strings), screenWidth, screenHeight, cellWidth, cellHeight, and filter settings.volume and sound player settings.KeyA, ArrowLeft) to game actions like LEFT, RIGHT, UP, DOWN, and ACTION via the controls object.messageBox and dialog appearance and behavior (e.g., dialogSpeed).const config = {
player: { sprite: 0, position: [2, 3] },
templates: {
x: { solid: true, sprite: 4, onCollide: (target) => target.remove() }
},
map: `
........
..x.....
........
`,
colors: ['#000', '#fff', '#f00'],
filter: { name: 'crt' }
};