Project Structure

Below is an example project structure for a Viber3D game. Your actual folder names may differ, but these are the typical directories and files you'll see.

viber3d/
├── src
│   ├── assets/                 # 3D models, textures, images
│   ├── components/             # React components for rendering 3D objects/UI
│   ├── systems/                # ECS Systems for game logic updates
│   ├── traits/                 # ECS Traits (components) describing entity data
│   ├── utils/                  # Utility functions (math, sorting, spatial hashing)
│   ├── actions.ts              # Central actions to spawn or modify entities
│   ├── app.tsx                 # Main React component (root of your 3D scene)
│   ├── frameloop.ts            # Main ECS update loop
│   ├── index.css               # Global CSS or Tailwind CSS (if used)
│   ├── main.tsx                # React app root, renders <App />
│   ├── startup.tsx             # Startup logic (initial spawns, intervals)
│   └── world.ts                # Creates the ECS world with default traits
├── index.html                  # Basic HTML page with root div
├── package.json                # Project dependencies and scripts
└── tsconfig.json               # TypeScript configuration

Key Directories

/src/assets
Contains static assets such as textures, images, 3D models (.glb or .gltf), or audio files.

/src/components
React components that render your entities or UI elements. For example:

• player-renderer.tsx
• enemy-renderer.tsx
• score-tracker.tsx
• postprocessing.tsx

/src/systems
ECS Systems that update game logic every frame. Examples:

• move-entities.ts
• camera-follow-player.ts
• handle-shooting.ts
• update-bullet-collisions.ts

/src/traits
Traits (a.k.a. ECS components) that store data about your entities, such as:

• is-player.ts
• health.ts
• movement.ts
• bullet.ts
• spatial-hash-map.ts

/src/utils
Helper functions or classes, e.g.:

• spatial-hash.ts
• sort-entities-by-distance.ts
• between.ts

Key Files

actions.ts
Central location for spawning or modifying entities (e.g. spawnPlayer, spawnBullet).

app.tsx
Your main game component, often where you set up the Three.js canvas (<Canvas> from React Three Fiber) and add your top-level components like <CameraRenderer>, <PlayerRenderer>, etc.

frameloop.ts
The main ECS update loop that orchestrates all the systems every frame.

startup.tsx
Initial spawns, intervals, or timed events (like adding more enemies every few seconds).

world.ts
Creates the ECS world (from koota or your chosen ECS library), defines default traits (Time, SpatialHashMap, etc.).