Metadata-Version: 2.4
Name: everythingcubic
Version: 0.1.2
Summary: A reusable 3D grid-based programming puzzle engine.
Author: EverythingCubic
Project-URL: Homepage, https://everythingcubic.com
Project-URL: Documentation, https://everythingcubic.com
Keywords: 3d,simulation,programming,puzzle,ai,reinforcement-learning,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# EverythingCubic

EverythingCubic is a reusable 3D grid-based programming puzzle engine.

The engine lets you build programs from programming blocks, execute those programs in a simulated 3D world, and evaluate the resulting state against objectives.

It is designed to be useful for:

- Building and experimenting with 3D programming puzzles
- Creating custom EverythingCubic problems
- Running the simulation locally
- Developing new objectives and mechanics
- Experimenting with program execution
- Building educational programming experiences
- Research and experimentation with the EverythingCubic simulation
- Developing tools and applications on top of the EverythingCubic engine

## Installation

Install EverythingCubic from PyPI:

    pip install everythingcubic

## What is included?

The Python package contains the reusable EverythingCubic engine.

    everythingcubic/
    ├── evaluator.py
    ├── problem.py
    ├── world_config.py
    ├── levels/
    ├── objectives/
    ├── programming/
    └── simulation/

### Simulation

The simulation package contains the core 3D world mechanics, including:

- Cubes
- Movement
- Rotation
- Gravity
- Floors
- Holes
- Ice
- Switches
- Boxes
- Entities
- Lasers
- Reflectors
- Octahedrons
- Collision handling
- World state
- History and replay state
- Colors and painting
- Quaternions
- Shapes

### Programming

The programming package provides the system used to construct and execute cube programs.

It includes:

- Programming blocks
- Programs
- Repeat blocks
- Program compilation
- Action limits
- Cube API
- Program execution

For example, a program can be constructed using the programming package:

    from everythingcubic.programming.program import Program

The programming API is modular so applications can build their own interfaces and program editors.

### Objectives

EverythingCubic provides reusable objective types for evaluating simulation results.

Examples include:

- Reaching a goal
- Reaching a floor
- Placing an entity at a position
- Hitting an octahedron with a laser
- Painting cells
- Painting target cells

Applications can use these objectives to create their own problems without implementing the simulation rules themselves.

### Problems

The `Problem` model combines a starting world, available programming blocks, action limits, and objectives into a reusable puzzle definition.

This makes it possible to define custom problems using the engine.

### Levels

The package currently includes the existing EverythingCubic levels.

Levels can be discovered through the package's level system, allowing applications to work with the bundled problems without depending on the EverythingCubic website backend.

## Example

A problem can be evaluated using the reusable engine.

The exact example will be documented using the public API provided by the package.

## Package Philosophy

EverythingCubic is intended to provide the reusable engine, not the entire EverythingCubic website.

The package focuses on the parts that developers, researchers, educators, students, and other applications can build upon.

The package does not provide the EverythingCubic website infrastructure.

In particular, the package does not contain:

- User accounts
- Authentication
- PostgreSQL
- Database migrations
- User progress tracking
- Website APIs
- FastAPI application infrastructure
- Auth0 integration
- Website-specific repositories and services
- Frontend code
- Community features
- Centralized puzzle sharing and discovery

These are part of the EverythingCubic website and application infrastructure rather than the reusable Python engine.

## Dependencies

The core EverythingCubic engine currently has no third-party runtime dependencies.

It uses Python's standard library for its runtime functionality.

## Python Version

EverythingCubic currently requires Python 3.12 or newer.

## Development

The EverythingCubic source repository contains the complete project, including the Python engine, website backend, frontend, and development infrastructure.

The Python package can be used independently of the website.

## License

License information will be added here.
