README_EN.md

Third-Person-MC (Web Third-Person MC / Web3D Demo)

中文 | English

A Web 3D demonstration built with Three.js + Vue 3, showcasing Minecraft-style multi-world portals and Souls-like target locking combat. Goal: To make Web3D a project that is "runnable, playable, and iteratively improvable," rather than just a screenshot demo.

• Online Preview: https://third-person-mc.vercel.app/
• Debug Panel: https://third-person-mc.vercel.app/#debug
• Product Requirements (PRD, early version, may vary from final implementation): docs/PRD.md

Table of Contents

• Visual Preview
• Gameplay & Controls
• Biomes & Terrain Generation
• Camera Adaptation & HUD
• Technology Stack
• Project Structure
• Credits
• TODO
• Quick Start
• License

Visual Preview

Start Screen

Attack Effect	Terrain: Multi-Biome Mosaic
Attack Effect Preview	Terrain: Multi-Biome Mosaic

Core Highlights (Project Realization)

• Movement System: Third-person character movement and stance switching (Walk/Run/Jump), emphasizing control feedback and animation blending.
• Biomes: Procedural terrain based on random seeds and noise (includes Plains, Forest, Desert, Frozen Ocean, etc.).
• Third-Person Camera: Obstacle avoidance and anti-clipping logic for uneven terrain, enhancing playability and visual stability.

Note: The repository also integrates HUD/Menu UI, resource loading, shader pipelines, and other infrastructure. See "Project Structure" and PRD for details.

Gameplay & Controls

Aimed at "onboarding readers within 30 seconds."

Action	Key	Description
Move	W / A / S / D	8-directional movement with stance switching
Normal Attack	Z	Supports combo sequences
Heavy Attack	X	Powerful hit feedback
Lock Target	Middle Mouse	(WIP) Souls-like locking logic
Block	C	Defensive action
Interact	E / F	(WIP) Gathering or opening portals
Close Menu	ESC	Exit or pause

Biomes & Terrain Generation

Terrain emphasizes "Voxel style + Procedural Biome transitions" while maintaining a stable frame rate.

Plains	Forest
Plains Biome	Forest Biome

Birch Forest	Cherry Blossom
Birch Forest Biome	Cherry Blossom Biome

Desert	Frozen Ocean
Desert Biome	Frozen Ocean Biome

Terrain Generation Logic (Noise & FBM)

One Seed, One World (PRNG)

Amplitude Adjustment (Noise)	Detail Adjustment (FBM)
Terrain Amplitude	Ground Details

Camera Adaptation & HUD

Core Goal: Free camera rotation, automatic obstacle avoidance without clipping through terrain.

HUD UI Overview

Camera Following	Over-the-Shoulder
Camera Follow Demo	Camera Stance Adj.

Technology Stack

Core Framework

• Three.js (v0.172+): Core 3D engine
• Vue 3: UI development framework
• Vite: Ultra-fast build tool and dev server
• Pinia: Reactive state management (Sync UI & 3D)

Rendering & Animation

• GLSL (Custom Shaders): Portals, terrain rendering, and post-processing
• three-custom-shader-material: Material enhancement plugin
• GSAP: High-performance animation library
• InstancedMesh: Optimized large-scale voxel and vegetation rendering

Tools & Engineering

• mitt: Global event bus for real-time UI/3D communication
• Tailwind CSS: Utility-first CSS framework
• Sass/PostCSS: Preprocessor support
• Playwright: E2E testing
• Husky & Commitlint: Git commit standards

Project Structure

E:\圖形學\Third-Person-MC\
├── public/                 # Static assets
│   ├── models/             # GLB/GLTF models (Character, Blocks)
│   ├── textures/           # Textures (Environment, Blocks, HUD)
│   └── fonts/              # Minecraft fonts
├── src/
│   ├── components/         # Vue UI components
│   │   ├── hud/            # In-game HUD (Health, XP, Hotbar, etc.)
│   │   ├── menu/           # Main Menu, Settings, Loading screens
│   │   └── MiniMap.vue     # Minimap component
│   ├── js/                 # Core logic
│   │   ├── camera/         # Camera Controller & Rig
│   │   ├── world/          # Scene elements, Player logic, Terrain system
│   │   │   └── terrain/    # Biome gen, Chunk management, AO calculation
│   │   ├── interaction/    # Raycasting, Block interaction
│   │   ├── utils/          # Debug, Events, Input handling
│   │   └── experience.js   # Framework singleton entry
│   ├── shaders/            # Custom GLSL shaders
│   └── vue/                # Pinia Stores
├── docs/                   # Documentation & Plans
└── vite.config.js          # Vite config

Credits

• Models: Custom Minecraft-style modeling ( character.glb ), skins from https://www.minecraftskins.com/
• Textures: Extracted from Minecraft Mojang/bedrock-samples, optimized by hexianWeb.
• Fonts: Minecraftia-Regular.ttf
• SFX: Planned to be generated by Suno AI (Hit, Ambience Not yet generated)

TODO

• Player's Loyal Dog: Companion AI and follow system
• Better Biomes: Smooth transitions and more vegetation types
• Inventory System: Items management and interaction UI
• Digging Effects: Block breaking particles and animations
• Skin Switching: Real-time player skin updates
• Locked Target FX: Enhanced visual feedback for Souls-like locking

Quick Start

Prerequisites

• Node.js (LTS recommended)
• Package Manager: pnpm recommended (repository includes pnpm-lock.yaml)

Installation & Run

pnpm install
pnpm dev

Open the local address provided by terminal (Vite starts with --host).

Common Commands

# Develop
pnpm dev

# Build / Preview
pnpm build
pnpm preview

# Lint
pnpm lint
pnpm lint:fix

# E2E (Playwright)
pnpm test:chrome
pnpm test:firefox
pnpm test:safari

Docs & Entry Points

• PRD: docs/PRD.md
• Planning: docs/plans/

Development Conventions

• Core logic organized via Experience Singleton in src/js/experience.js
• Decoupled UI (Vue) and 3D (Three.js): State via Pinia, events via mitt
• New 3D components should include a debugInit panel for tuning

(See .cursor/rules/ for more details)

Contribution

• Code of Conduct: CODE_OF_CONDUCT.md
• Husky + Commitlint enabled, follow Conventional Commits

License

MIT, see LICENSE.