# Threejs Implementation Guideline ## Introduction Three.js is a powerful, open-source JavaScript library that simplifies the process of creating and displaying 3D graphics and animations on the web, leveraging WebGL for GPU-accelerated rendering. Keep the files in the src/app directory structure for Next.js compatibility. ## Critical Implementation Notes - **CRITICAL**: All ThreeJS code MUST be run on the client side using 'use client' directive in Next.js components - **CRITICAL**: Always implement the stats monitor on the top right of the screen using the stats.js library. - **CRITICAL**: No mobile controls or control box please keep it simple with stats monitor. (Unless users states it) ## Project Structure for 3D Space Environments ### Basic 3D Space Environment For a very basic start to this app just use the `src/app/templates/space/components/space-environment.tsx` template component file directly in the `src/app/page.tsx` to get a working app. ```tsx 'use client' import SpaceEnvironment from './templates/space/components/space-environment' export default function HomePage(): JSX.Element { return } ``` ### 3D Space Environment with a Spaceship that can be controlled by the user ```tsx 'use client' import SpaceEnvironmentWithSpaceship from './templates/space/space-environment-with-spaceship' export default function HomePage() { return ; } ``` ### 3D Minecraft like Voxel World (Not Minecraft player controlled game) - You don't need any stats monitor or mobile controls for this. ```tsx 'use client' import { useState } from 'react' import { VoxelWorld } from './templates/minecraft-like-voxel-world' import { BlockProps } from './templates/minecraft-like-voxel-world/Block' export default function HomePage() { const [activeBlockType, setActiveBlockType] = useState('wood'); return (

) } ``` #### Optional: Add a toolbar to select the block type to place On top of this template files you can add a toolbar to select the block type to place. Might need to update the src/app/page.tsx file to include the VoxelToolbar component. example for `src/app/VoxelToolbar.tsx` ```tsx 'use client' import { BlockProps } from "./templates/minecraft-like-voxel-world/Block" const BLOCK_TYPES: BlockProps['blockType'][] = ['grass', 'dirt', 'stone', 'wood'] interface VoxelToolbarProps { activeBlockType: BlockProps['blockType'] onBlockTypeChange: (type: BlockProps['blockType']) => void } export function VoxelToolbar({ activeBlockType, onBlockTypeChange }: VoxelToolbarProps) { return (

Add Block:

{BLOCK_TYPES.map(blockType => ( ))}

) } ``` #### Optional: Add a stats monitor to the top right of the screen using the stats.js library. Example file to create [not available in template] `src/app/PerformanceStats.tsx`. ```tsx 'use client' import { useEffect, useRef } from 'react' import Stats from 'stats.js' interface PerformanceStatsProps { blockCount?: number } export function PerformanceStats({ blockCount = 0 }: PerformanceStatsProps) { const statsRef = useRef() const containerRef = useRef(null) useEffect(() => { if (!containerRef.current) return const fpsStats = new Stats() fpsStats.showPanel(0) fpsStats.dom.style.position = 'relative' fpsStats.dom.style.marginBottom = '4px' const msStats = new Stats() msStats.showPanel(1) msStats.dom.style.position = 'relative' msStats.dom.style.marginBottom = '4px' const memStats = new Stats() memStats.showPanel(2) memStats.dom.style.position = 'relative' const panels = [fpsStats.dom, msStats.dom, memStats.dom] panels.forEach(panel => { panel.style.width = '80px' panel.style.height = '48px' }) containerRef.current.appendChild(fpsStats.dom) containerRef.current.appendChild(msStats.dom) containerRef.current.appendChild(memStats.dom) function animate() { fpsStats.begin() msStats.begin() memStats.begin() fpsStats.end() msStats.end() memStats.end() requestAnimationFrame(animate) } animate() statsRef.current = fpsStats return () => { if (containerRef.current) { containerRef.current.innerHTML = '' } } }, []) return (

Performance

Blocks: {blockCount}

Draw Calls: ~{blockCount}

FPS • MS • MB

) } ``` Might need to update the src/app/page.tsx file to include the PerformanceStats component. ```tsx 'use client' import { useState } from 'react' import { VoxelWorld } from './templates/minecraft-like-voxel-world' import { VoxelToolbar } from './VoxelToolbar' import { PerformanceStats } from './PerformanceStats' import { BlockProps } from './templates/minecraft-like-voxel-world/Block' export default function HomePage() { const [activeBlockType, setActiveBlockType] = useState('wood'); const [blockCount, setBlockCount] = useState(0); return (

) } ``` ### 3D Minecraft FPP Game - You already have some template files in the `src/app/components/minecraft` directory like Block.tsx, Clouds.tsx and WorldGenerator.tsx. - You need to create a index.ts, MinecraftGame.tsx, FirstPersonControls.tsx and types.ts file for the game. - Will be better if you create these files in the `src/app/components/minecraft` directory and then export them in the index.ts file and use that in the src/app/page.tsx file. `src/app/components/minecraft/index.ts` ```ts export * from './Block' export * from './Clouds' export * from './WorldGenerator' ``` #### Example file for `src/app/components/minecraft/types.ts` ```ts export interface Position { x: number y: number z: number } export interface Block { type: BlockType position: Position } export type BlockType = 'grass' | 'dirt' | 'stone' | 'water' | 'sand' | 'wood' export interface MinecraftGameProps { worldSize?: number playerStartPosition?: Position } export interface World { blocks: Block[][][] size: number } ``` #### Example file for `src/app/components/minecraft/index.ts` ```ts export { MinecraftGame } from './MinecraftGame' export { Block } from './Block' export { FirstPersonControls } from './FirstPersonControls' export { generateWorld, getVisibleBlocks } from './WorldGenerator' export { Clouds } from './Clouds' export type { MinecraftGameProps, Position, Block as BlockType, BlockType as BlockTypeEnum, World } from './types' ``` #### Example file for `src/app/components/minecraft/MinecraftGame.tsx` ```tsx import { useMemo, useState, useEffect } from 'react' import { Canvas } from '@react-three/fiber' import { Block } from './Block' import { FirstPersonControls } from './FirstPersonControls' import { generateWorld, getVisibleBlocks } from './WorldGenerator' import { Clouds } from './Clouds' import { MinecraftGameProps, Position, World } from './types' export function MinecraftGame({ worldSize = 24, playerStartPosition = { x: 12, y: 15, z: 12 } }: MinecraftGameProps) { const [world, setWorld] = useState(null) const [isClient, setIsClient] = useState(false) useEffect(() => { setIsClient(true) const generatedWorld = generateWorld(worldSize) setWorld(generatedWorld) }, [worldSize]) const visibleBlocks = useMemo(() => world ? getVisibleBlocks(world) : [], [world] ) const actualStartPosition = useMemo(() => { if (!world) return playerStartPosition const x = playerStartPosition.x const z = playerStartPosition.z let groundHeight = 0 for (let y = 31; y >= 0; y--) { if (world.blocks[Math.floor(x)]?.[y]?.[Math.floor(z)]) { groundHeight = y + 1 break } } return { x, y: groundHeight + 2, z } // Spawn 2 blocks above ground }, [world, playerStartPosition]) const [playerPosition, setPlayerPosition] = useState(actualStartPosition) // Don't render anything until client-side if (!isClient || !world) { return (

Loading Minecraft World...

) } return (

Sound2Life