---
title: NPCverse
emoji: ⚔️
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 6.16.0
python_version: "3.12"
app_file: app.py
pinned: true
license: mit
short_description: Turn anyone into a living RPG character
full_width: true
tags:
  - zerogpu
  - gradio-server
  - image-to-text
  - rpg
  - character-generation
---

<!--
Sharing is Caring badge note:
After building with Codex/Claude Code, run this ONE command:
hf upload YOUR_USERNAME/npcverse-codex-traces ~/.codex/sessions . --repo-type dataset
Replace YOUR_USERNAME with your actual HuggingFace username.
This uploads your Codex session files and earns the "Sharing is Caring" badge.
The traces will be visible at: https://huggingface.co/datasets/YOUR_USERNAME/npcverse-codex-traces
-->

# NPCverse

NPCverse turns any uploaded photo into a living RPG character. Upload a portrait, summon a character sheet, then chat with the generated NPC as their lore, powers, quests, secrets, and friendship level evolve.

This HuggingFace Space is built as a fast hackathon demo with a dark RPG web UI, a Gradio Server backend, ZeroGPU allocation, and a PIL-based share-card generator so each summoned character can be exported as a collectible PNG.

## How It Works

1. Upload or drag a photo into the NPCverse summoning portal.
2. The backend analyzes the image with a multimodal vision-language model.
3. NPCverse transforms the visual description into structured RPG character JSON.
4. The frontend renders stats, rarity, abilities, lore, quests, secrets, and friendship progress.
5. Chat with the NPC in character, unlock secrets over time, and export a share card.

## Model

NPCverse uses [`openbmb/MiniCPM-V-4.6`](https://huggingface.co/openbmb/MiniCPM-V-4.6), a lightweight 1.3B image-text-to-text model from OpenBMB. The model handles both visual analysis and character/chat generation through the HuggingFace Transformers integration.

## Badges

- ZeroGPU Explorer
- Spaces Builder
- AI Character Creator
- Sharing is Caring

## Local Development

```bash
git clone https://huggingface.co/spaces/build-small-hackathon/NPCverse
cd NPCverse
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

# Optional: create a .env file if you hit Hub rate limits locally
# echo HF_TOKEN=hf_... > .env

python app.py
```

Open `http://localhost:7860` after the server starts. The model (`openbmb/MiniCPM-V-4.6`, ~3 GB) will be downloaded from the Hub on first run.

## Environment Variables

| Variable | Required | Notes |
| --- | --- | --- |
| `HF_TOKEN` | No | Not required for the public `openbmb/MiniCPM-V-4.6` model, but useful locally if you hit Hub rate limits or use private assets. |

## Hackathon

NPCverse is a submission for Build Small Hackathon 2026, Track 2.