🐱 Run The Cat

👩‍💻 Student Information

Name : Nadia Azzahra Putri Arvi
Student ID : 20210747
Email : nadia.arvi@kaist.ac.kr

📃 Table of Contents

• 🐱 Run The Cat
  • 👩‍💻 Student Information
  • 📃 Table of Contents
  • 🎮 Game Description
    • 🕹️ How It Works
  • ⚙️ Installing & Running The Game
  • 🔧 Code Structure
    • 🐙💻 Repository Structure
    • 🧩 Key Modules and Responsibilities
  • 📦 Tech Stack & Resources
    • 🔧 Built With
    • 🕹️ Game Framework & Libraries
    • 🎨 Assets Used
  • 🐛 Known Issues
  • ✨ Special Features
  • 🙏 Acknowledgements

🎮 Game Description

Run The Cat is a puzzle-platformer game where players guide a cat through various levels using coding-like commands. The game teaches basic programming concepts through interactive gameplay.

🕹️ How It Works

Figure 1. A snapshot of the game interface showing key UI components.

In this game, players must:

1. Select commands from the blocks panel — only these available blocks can be used.
2. Arrange the selected blocks into a sequence using the steps panel.
3. Define macro commands in the loop panel to optimize and reduce repetition.
4. Execute the move using the run button to guide the cat.
5. Collect keys and reach the flag to complete the level.

⚙️ Installing & Running The Game

To play the game, follow these steps:

1. Clone the repository

git clone https://github.com/nadiarvi/run-the-cat.git

2. Navigate to the project directory:

cd run-the-cat

3. Install dependencies and start the game:

npm install
npm run dev

🔧 Code Structure

Figure 2. UML Diagram and Class Relations

🐙💻 Repository Structure

run-the-cat/
├── README.md
├── index.html                   # Main HTML file to load the game
├── lib/                         # External libraries (p5.js, SceneManager, etc.)
│   ├── p5.clickable.js          
│   ├── p5.js                    
│   ├── scenemanager.js          
│   └── scenemanager_.js         
├── package.json                 # Project metadata and dependencies
├── public/
│   └── assets/                  # Images, sprites, and other media assets
└── src/                         # Main source code
    ├── components/              # Reusable game components (Cat, Flag, etc.)
    ├── main.js                  # Game entry point
    ├── scenes/                  # Level or scene logic
    ├── style.css                # Styles for the game UI
    └── utils/                   # Utility functions and UI helpers

🧩 Key Modules and Responsibilities

• index.html: Entry point of the application; initializes canvas and loads all scripts.
• lib/: Contains external libraries such as p5.js, p5.clickable, and p5.SceneManager for rendering, UI, and scene handling.
• public/assets/: Includes all images, sprites, and media used in the game and README visuals.
• src/components/: Contains constructors for individual game elements such as:
  • Cat: Handles player character movement, physics, and animation.
  • Key and Flag: Interactive objects related to level progression.
• src/scenes/: Implements level logic using SceneManager.
• src/utils/: Includes styling helpers, themes, and reusable UI logic.
• main.js: Boots up the game and loads the initial scene.
• style.css: Provides global styling for in-game UI and layout.

📦 Tech Stack & Resources

🔧 Built With

Tech	Description
	Markup structure
	Styling and layout
	Game logic and interactivity
	Development tooling

🕹️ Game Framework & Libraries

Library	Purpose
	Core game rendering and animation
p5.SceneManager	Manage different game scenes and levels
p5.clickable	Create clickable UI elements (i.e. buttons)
p5.play	Sprite handling and physics engine

🎨 Assets Used

Asset	Source & Credits
🐱 Cat Sprite	Free Street Animal Pixel Art Asset Pack by CraftPix.net
🚩 Flag Animation	Free Flag with Animation by ankousse26
🔑 Key Sprite	FREE Pixel Art Key Pack – Animated by karsiori

🐛 Known Issues

• Restart Bug
  After restarting a level, the cat's movement becomes slightly jittery, unlike on a fresh load. This is likely due to the sprite or state not being fully reset. A temporary fix is in place, but it may still cause minor visual glitches.

• Clickable Background After Completion
  When a level is completed and the overlay is displayed, the background remains interactive. This allows players to accidentally trigger cat movement even though the game should not be playable.

• Sprite Can Move Outside the Frame
  When the Cat sprite moves beyond the visible frame, it becomes unresponsive to controls. Currently, there is no boundary-checking logic implemented to prevent the sprite from leaving the playable area.

✨ Special Features

No additional features beyond the core requirements were implemented.

🙏 Acknowledgements

All assets and libraries used have been credited in the 📦 Tech Stack & Resources section above. Code examples were referenced from the official documentation of the respective libraries. LLMs were used for debugging assistance.