| --- |
| 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. |
|
|
