HyperSim

A Python framework for 4D visualization and simulation. This project provides tools for working with 4D geometry, including 4D objects, transformations, and visualizations.

Features

• 4D geometric primitives (hypercube/tesseract, 4D simplex, 16-cell)
• 4D to 3D perspective projection utilities
• Interactive visualization using Pygame (real-time controls)
• Extensible architecture for adding new 4D objects and renderers
• NEW: Cross-dimensional game engine with playable 1D→2D→3D→4D progression
• Entity Component System (ECS) for flexible gameplay
• Dimension-specific controllers, renderers, and AI systems
• Campaign/progression system with save/load support

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/hypersim.git
   cd hypersim

2. Create and activate a virtual environment:

   python -m venv venv
   .\venv\Scripts\activate  # On Windows
   source venv/bin/activate  # On Unix/macOS

3. Install the package in development mode:

   pip install -e .

Quick Start

import pygame
from hypersim.objects import Hypercube
from hypersim.visualization import PygameRenderer, Color

# Create a renderer window
renderer = PygameRenderer(width=1024, height=768, title="HyperSim - Tesseract")

# Create a hypercube, tweak initial transform
cube = Hypercube(size=1.5)
cube.set_position([0, 0, 0, 1.0])
cube.rotate(xy=0.3, xw=0.2, zw=0.1)

# Minimal render loop
running = True
clock = pygame.time.Clock()
while running:
    for ev in pygame.event.get():
        if ev.type == pygame.QUIT:
            running = False
    if hasattr(renderer, 'clear'):
        renderer.clear()
    renderer.render_4d_object(cube, Color(80, 200, 255), 2)
    pygame.display.flip()
    clock.tick(60)
pygame.quit()

Project Structure

hypersim/
├── hypersim/               # Main package
│   ├── core/              # Core simulation and math
│   ├── objects/           # 4D object definitions
│   └── visualization/     # Visualization components
├── examples/              # Example scripts
├── tests/                 # Unit and integration tests
└── docs/                  # Documentation

Running Examples

Check the examples/ directory for example scripts. To run the included examples:

# Visualization demos
python examples/pygame_simplex.py
python examples/pygame_sixteen_cell.py

# Play the game (NEW!)
python examples/play_game.py              # Full playable game
python -m hypersim.cli --demo play        # Alternative: via CLI

# Other demos
python examples/game_session_bootstrap.py  # progression/campaign bootstrap
python -m hypersim.cli --demo game         # progression-enabled sandbox mode

Playing the Game

HyperSim now includes a playable cross-dimensional adventure! Start as a 1D being on a line and ascend through dimensions.

Controls:

• A/D or Arrow Keys: Move (1D)
• WASD: Move in plane (2D)
• E: Interact with portals
• Space: Use ability
• P: Pause
• R: Restart level
• ESC: Quit

Gameplay:

1. Start in 1D - you're a point on a line with limited visibility
2. Collect energy orbs and avoid enemies
3. Reach the portal to ascend to 2D
4. In 2D, explore the plane with full directional movement
5. Continue ascending through 3D and eventually 4D!

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.