SenangWebs Xperience (SWX)

A lightweight JavaScript library for creating grid-based interactive experiences on the web. Perfect for building simple games, interactive tutorials, and grid-based applications.

Features

• Dual API - Use HTML data attributes OR JavaScript API
• Simple & Intuitive - Easy to learn and use
• Lightweight - Minimal dependencies, small bundle size
• Flexible - Customizable grid sizes and styling
• Auto-initialization - Automatic setup from HTML markup
• Interactive Objects - Static, dynamic, and interactive game objects
• Built-in Controls - WASD + Arrow keys + Spacebar support

Installation

Option 1: Download

Download the latest release and include in your HTML:

<script src="https://unpkg.com/senangwebs-xperience@latest/dist/swx.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/senangwebs-xperience@latest/dist/swx.min.css" />

Option 2: Build from Source

npm install
npm run build

Quick Start

HTML API (Declarative)

Create an interactive grid using just HTML data attributes:

<div data-swx data-swc-cols="15" data-swc-rows="10" data-swc-unit="32px">
    <!-- Player -->
    <div data-swx-player data-swc-position="5 5" data-swc-size="1 1">
        <div data-swx-player-idle>🧍</div>
        <div data-swx-player-left>🚶</div>
        <div data-swx-player-right>🚶‍➡️</div>
        <div data-swx-player-up>🔼</div>
        <div data-swx-player-down>🔽</div>
    </div>

    <!-- Static walls -->
    <div data-swx-static data-swc-position="1 1" data-swc-size="1 10">🧱</div>

    <!-- Dynamic box (pushable) -->
    <div data-swx-dynamic data-swc-position="3 3" data-swc-size="1 1">📦</div>

    <!-- Interactive door -->
    <div data-swx-interact="openDoor()" data-swc-position="8 8" data-swc-size="1 1">🚪</div>
</div>

<script src="swx.min.js"></script>
<script>
    function openDoor() {
        alert('You opened the door!');
    }
</script>

JavaScript API (Programmatic)

Or create the same experience using JavaScript:

const swx = new SWX({
    cols: 15,
    rows: 10,
    unit: '32px',
});

swx.init();

// Add player
swx.addPlayer({
    position: { x: 5, y: 5 },
    size: { width: 1, height: 1 },
    sprites: {
        idle: '🧍',
        left: '🚶',
        right: '🚶‍➡️',
        up: '🔼',
        down: '🔽',
    },
});

// Add static object (wall)
swx.addStaticObject({
    position: { x: 1, y: 1 },
    size: { width: 1, height: 10 },
    content: '🧱',
});

// Add dynamic object (pushable box)
swx.addDynamicObject({
    position: { x: 3, y: 3 },
    size: { width: 1, height: 1 },
    content: '📦',
});

// Add interactive object (door)
swx.addInteractiveObject({
    position: { x: 8, y: 8 },
    size: { width: 1, height: 1 },
    content: '🚪',
    onInteract: () => {
        alert('You opened the door!');
    },
});

Controls

• W or ↑ - Move up
• S or ↓ - Move down
• A or ← - Move left
• D or → - Move right
• Space - Interact with adjacent objects

API Reference

Constructor

const swx = new SWX(options);

Options:

• container (HTMLElement) - Container element for the grid
• cols (number) - Number of columns (default: 10)
• rows (number) - Number of rows (default: 10)
• unit (string) - Size of each cell (default: '32px')

Methods

swx.init()

Initialize the grid system.

swx.addPlayer(config)

Add a player to the grid.

Config:

{
    position: { x: 5, y: 5 },
    size: { width: 1, height: 1 },
    sprites: {
        idle: '🧍',
        left: '🚶',
        right: '🚶‍➡️',
        up: '🔼',
        down: '🔽'
    }
}

swx.addStaticObject(config)

Add an immovable object (walls, barriers).

Config:

{
    position: { x: 1, y: 1 },
    size: { width: 1, height: 1 },
    content: '🧱'
}

swx.addDynamicObject(config)

Add a pushable object (boxes, crates).

Config:

{
    position: { x: 3, y: 3 },
    size: { width: 1, height: 1 },
    content: '📦'
}

swx.addInteractiveObject(config)

Add an interactive object that triggers callbacks.

Config:

{
    position: { x: 8, y: 8 },
    size: { width: 1, height: 1 },
    content: '🚪',
    onInteract: () => {
        // Your interaction logic
    }
}

swx.removeObject(object)

Remove an object from the grid.

swx.getObjectsByType(type)

Get all objects of a specific type ('static', 'dynamic', 'interactive').

swx.destroy()

Clean up and destroy the SWX instance.

SWX.autoInit() (Static)

Automatically initialize all [data-swx] elements in the document.

HTML Data Attributes

Container Attributes

• data-swx - Mark element as SWX container
• data-swc-cols="15" - Number of columns
• data-swc-rows="10" - Number of rows
• data-swc-unit="32px" - Cell size

Object Attributes

• data-swx-player - Player object
• data-swx-static - Static object (immovable)
• data-swx-dynamic - Dynamic object (pushable)
• data-swx-interact="functionName()" - Interactive object

Position & Size

• data-swc-position="x y" - Position in grid (e.g., "5 5")
• data-swc-size="width height" - Object size (e.g., "1 1")

Player Sprites

• data-swx-player-idle - Idle sprite
• data-swx-player-left - Left movement sprite
• data-swx-player-right - Right movement sprite
• data-swx-player-up - Up movement sprite
• data-swx-player-down - Down movement sprite

Styling

SWX includes minimal base styles. You can customize the appearance:

/* Customize grid container */
[data-swx] {
    background: #e5e7eb;
    border-radius: 8px;
}

/* Customize player */
.swx-player {
    font-size: 2em;
}

/* Customize objects */
.swx-static {
    background: rgba(0, 0, 0, 0.1);
}

.swx-dynamic {
    cursor: grab;
}

.swx-interactive {
    animation: pulse 1s infinite;
}

Examples

Check the examples/ folder for complete examples:

• html-api.html - Basic example using HTML data attributes
• js-api.html - Same example using JavaScript API
• advanced.html - Complex puzzle game (Sokoban-style)

Development

# Install dependencies
npm install

# Development build with watch
npm run watch

# Development build
npm run dev

# Production build
npm run build

Object Types

Static Objects

• Cannot be moved by the player
• Block player movement
• Examples: walls, barriers, obstacles

Dynamic Objects

• Can be pushed by the player
• Block movement but can be moved
• Examples: boxes, crates, boulders

Interactive Objects

• Trigger callbacks when interacted with (spacebar)
• Can be set to block movement or not
• Examples: doors, switches, NPCs, items

Use Cases

• Grid-based puzzle games
• Interactive tutorials
• Map navigation interfaces
• Educational applications
• Retro-style games
• Creative interactive experiences

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - See LICENSE.md for details