GameViz HyperKit

GameViz HyperKit is a lightweight Python SDK for building complete small 2D hypercasual and hybrid-casual games with a code-first workflow.

It is designed for beginners, students, game-jam developers, indie developers, and small teams that want a focused Python toolkit for mobile-style 2D games.

HyperKit is not a general-purpose engine like Unity, Unreal Engine, or Godot.
It focuses on a smaller 2D mobile-game scope with reusable runtime, physics, UI, input, persistence, audio, monetization, analytics, and project tooling.

Current Release Status

HyperKit is now in the v1.0.0 stable-release certification stage.

Current package status:

• Latest published PyPI release: 0.2.0
• Stable package version: 1.0.0
• Active development version: 1.0.0
• Installation command: pip install gameviz-hyperkit
• Package maturity: Production / Stable
• Public compatibility contract: API 1.0
• Frozen top-level public exports: 256
• Supported Python versions: Python 3.9–3.12

The 1.0 line preserves the frozen API established during the v0.9 public beta and adds final stable-release certification, package verification, and protected publication tooling. Real PyPI publication remains an explicit final action rather than an automatic side effect.

HyperKit is intended to support complete small 2D mobile games inside its focused scope. It is not intended to replace a full general-purpose 2D/3D engine.

Package Identity

• Package name: gameviz-hyperkit
• Import name: hyperkit
• CLI command: hyperkit
• License: MIT

Project Links

• PyPI Package
• GitHub Repository
• Issue Tracker
• Changelog
• Version History

Who Is HyperKit For?

HyperKit is useful for:

• Learning 2D game development with Python
• Building complete small hypercasual and hybrid-casual games
• Creating tap, swipe, runner, puzzle, quiz, and physics-style games
• Testing and shipping focused game concepts with a lightweight SDK
• Building game-jam and educational projects
• Students and indie developers who want a small code-first game toolkit

Main Features

• 2D game project structure
• Scene system
• GameObject system
• Tap and click input
• Swipe input
• Input action mapping
• Score and high-score system
• Save and persistence system
• Collision helpers
• Simple physics helpers
• Text labels and basic UI helpers
• Responsive virtual canvas scaling
• Asset loading helpers
• Image rendering support
• Audio playback helpers
• Tween and animation helpers
• Sprite animation helper
• Particle helper
• Camera shake helper
• Scene transition helper
• Timer and cooldown helpers
• Level data loading helper
• Camera follow helper
• Screen and world-bound helpers
• UI progress bar helper
• CLI project generator
• Ready-made starter templates
• Generated-project validation
• Project health and release validation commands
• Complete-game validation
• Project diagnostics CLI
• Runtime FPS/frame diagnostics
• Optional debug overlay
• Mobile performance profiles
• Frame-time hitch protection
• Fixed-step simulation helper
• Runtime service lifecycle hooks
• Scene resource cleanup
• Runtime safe-area updates
• Touch move-noise filtering
• Content manifests and tagged content lookup
• Reusable JSON-driven prefabs
• Cached JSON/CSV/TXT loading and preload helpers
• Level sequence/progression helper
• Reusable object pooling
• Sprite frame-pattern generation
• Distribution artifact verification
• SHA-256 release manifests
• Fresh-wheel clean-install verification
• Gated TestPyPI/PyPI Trusted Publishing workflow
• Production Android API 36/AAB profile
• Android signing readiness validation
• Signed Android production release workflow
• Frozen 1.0 public API contract
• Exact API-freeze validation
• Deterministic public API fingerprint
• Public-beta validation workflow
• Stable-release certification
• Stable-release evidence certificate
• Protected v1.0.0 publication workflow
• Python 3.9–3.12 CI workflow
• Experimental Android build configuration

Installation

Install from PyPI

pip install gameviz-hyperkit

Verify the installation:

hyperkit doctor
hyperkit list-templates

Install for Local Development

Clone the repository:

git clone https://github.com/RifatGameDev/gameviz-hyperkit.git
cd gameviz-hyperkit

Install HyperKit in editable development mode:

pip install -e ".[dev]"

Run the tests:

pytest

Quick Start

Create a Tap Counter project:

hyperkit new my-game --template tap-counter
cd my-game
hyperkit run

You may also launch the generated project directly:

python main.py

The name my-game is only an example. You can choose another project name:

hyperkit new flappy-project --template flappy-mini
cd flappy-project
hyperkit run

Generated projects include:

my-game/
├── main.py
├── README.md
├── hyperkit.toml
└── assets/
    ├── README.md
    ├── images/
    ├── audio/
    ├── fonts/
    └── data/

Available Templates

List all templates:

hyperkit list-templates

Underscore-style aliases are also accepted:

tap_counter
flappy_mini
swipe_runner
puzzle_game
quiz_game
simple_physics

Basic Example

from hyperkit import Game, GameObject, Scene, ScoreManager, TextLabel


class MyScene(Scene):
    def start(self):
        self.score = ScoreManager(
            high_score_key="my_game_high_score"
        )

        self.player = self.add(
            GameObject(
                x=300,
                y=500,
                width=100,
                height=100,
                color=(0.2, 0.75, 1.0, 1),
                shape="circle",
            )
        )

        self.score_label = self.add(
            TextLabel(
                x=30,
                y=1180,
                text="Score: 0",
                font_size=32,
                color=(1, 1, 1, 1),
            )
        )

        self.start_game()

    def on_tap(self, x, y):
        self.player.x = x - self.player.width / 2
        self.player.y = y - self.player.height / 2

        self.score.add(1)
        self.score_label.set_text(
            f"Score: {self.score.value}"
        )


game = Game(
    title="My HyperKit Game",
    width=720,
    height=1280,
)

game.set_scene(MyScene())
game.run()

For mobile runtime tuning, you can use a performance profile:

from hyperkit import Game, PerformanceProfile

game = Game(
    title="My HyperKit Game",
    performance_profile=(
        PerformanceProfile.from_mode(
            "balanced"
        )
    ),
    touch_move_min_distance=3,
)

Asset Folders

Generated HyperKit projects use this asset structure:

assets/
├── images/
├── audio/
├── fonts/
└── data/

FBX files are not directly supported.
For 2D projects, export source assets as PNG images, animation frames, or sprite sheets.

CLI Commands

Check the environment

hyperkit doctor

List templates

hyperkit list-templates

Create a project

hyperkit new my-game --template tap-counter

Enter the generated project

cd my-game

Run the project

hyperkit run

Show project metadata

hyperkit info

Validate the current project

hyperkit validate

Show developer diagnostics

hyperkit diagnostics

Validate complete built-in games

hyperkit validate-complete-games

Validate a content manifest

hyperkit validate-content --manifest content.json

Verify built Python distributions

hyperkit verify-dist
hyperkit release-manifest
hyperkit verify-clean-install

Check a package publishing target

hyperkit publish-check --target testpypi

The controlled real-PyPI workflow accepts only stable MAJOR.MINOR.PATCH versions and requires a matching v<version> Git tag.

Generate production Android configuration

hyperkit init-android --production --overwrite
hyperkit android-release-doctor

Validate the frozen 1.0 public API

hyperkit api-freeze-check

Run final stable-release certification

hyperkit stable-release-check

To write machine-readable certification evidence:

hyperkit stable-release-check --certificate dist/stable-release-certificate.json

Show the package health report

hyperkit health

Show release readiness

hyperkit release-check

Run the final pre-release audit

hyperkit pre-release-audit

Validate built-in templates

hyperkit validate-templates

Validate generated projects

hyperkit validate-generated-projects

Validate manual QA evidence

hyperkit validate-release-evidence

Require complete QA evidence

hyperkit validate-release-evidence --require-complete

Create experimental Android configuration

hyperkit init-android

Run the experimental Android build workflow

hyperkit build android

Development Commands

Install development dependencies:

pip install -e ".[dev]"

Run the complete test suite:

pytest

Build the wheel and source distribution:

python -m build

Validate the distribution files:

python -m twine check dist/*

Package publication is handled through the project's controlled release workflow.

Documentation

• Version History
• Changelog
• Templates Guide
• Template Helper Usage Guide
• Template Quality Checklist
• Release Readiness Checklist
• Generated Project Smoke Tests
• Project Health Report
• Release Build Automation
• Final Pre-release Audit
• Beginner Quick Start Tutorial
• Template Media Guide
• Template Screenshots and Demo Media
• CLI Error Messages
• Template Validation
• Production Template Polish Checklist
• Template Stabilization Checklist
• Template Manual QA Checklist
• Manual QA Result Template
• Release Evidence Structure
• Release Evidence Workspace
• HyperKit v0.5 — Complete Games + Developer Tooling
• HyperKit v0.6 — Mobile Production Runtime + Performance
• HyperKit v0.7 — Content, Assets + Advanced Game Features
• HyperKit v0.8 — Build, Publishing + Production Hardening
• HyperKit v0.9 — API Freeze + Public Beta
• HyperKit v1.0.0 — Stable Release
• Roadmap to HyperKit 1.0

Template Polish and Runtime Documentation

• Tap Counter Polish - Phase 48
• Flappy Mini Polish - Phase 49
• Swipe Runner Polish - Phase 50
• Puzzle Game Polish - Phase 51
• Quiz Game Polish - Phase 52
• Simple Physics Polish - Phase 53
• Template Polish Summary - Phase 54
• Generated Project Validation - Phase 55
• Template Runtime Readiness - Phase 56
• Runtime QA Tracker - Phase 58

Current Limitations

• HyperKit is not a general-purpose 2D/3D engine.
• Advanced 3D rendering is not supported.
• Android builds depend on the external Android/Buildozer toolchain and still require app-specific device/store release validation.
• AdMob and Firebase Analytics integrations exist, but production-provider configuration and release QA remain environment-dependent.
• The current focus is complete small 2D hypercasual and hybrid-casual mobile games.
• The stable API 1.0 contract covers the frozen top-level public surface; future incompatible changes require a major-version transition.
• A specific game's production readiness still depends on that game's own assets, signing, provider configuration, store requirements, and QA.

Roadmap

The active 1.0.0 line is the Stable Release milestone:

• preserve the frozen API 1.0 contract
• preserve the 256-name frozen top-level public surface
• require exact API fingerprint validation
• run Python 3.9–3.12 stable regression checks
• verify health, templates, complete games, generated projects, release readiness, and audit gates
• verify wheel/sdist, release manifests, and fresh-wheel installation
• generate a machine-readable stable-release certificate
• protect real-PyPI publication behind an explicit v1.0.0 tag and confirmation

After v1.0.0, compatible fixes may move to patch releases and compatible feature additions may move to later 1.x minor releases.

Contributing

Contributions, issue reports, and improvement suggestions are welcome.

Before submitting changes:

pip install -e ".[dev]"
pytest

Use the issue tracker to report bugs or request features.

License

GameViz HyperKit is distributed under the MIT License.

See LICENSE for details.

Author

Developed by Md. Rifat Hossain Chowdhury / GameViz.

• GitHub: RifatGameDev
• PyPI package: gameviz-hyperkit