diff --git a/docs/creativeConcept/3d_models.md b/docs/creativeConcept/3d_models.md new file mode 100644 index 0000000..8ce749c --- /dev/null +++ b/docs/creativeConcept/3d_models.md @@ -0,0 +1,167 @@ +--- +title: 3D models +sidebar_position: 3 +--- + +# 3D models + +## Conception in blender + +### View statistics (number triangles / objects) + +In blender, you can see the number of triangles, click on *viewport overlays*, and click on *statictics*, you can now see the statistics. + +![Viewport overlays](./static_files/blender_viewport_overlays.png) + +![display statictics](./static_files/blender_display_statistics.png) + + +### One mesh + +Each .blend file must have only 1 mesh, or 1 logical group. + +This avoids "who touched what" conflicts in version control. + +### LOD (Level Of Detail) management + +In the goal to keep performance in the game, we need to have 4 LOD. + +One you have created your mesh, rename it with the suffix *_LOD0*. + +Duplicate it with *alt + D* or in menu *Object* > *Duplicate Linked* and rename it with suffix *_LOD1*. +Repeat the duplicate for *_LOD2* and *_LOD3_*. + +On _LOD1, _LOD2 and _LOD3, add the modifier *Decimate*. Apply the ratio like this table: + + +| LOD | Decimate Ratio | Triangle target | +|-----|----------------|-----------------| +| LOD0 | 1.0 — no decimate | 100% | +| LOD1 | 0.5 | ~50% | +| LOD2 | 0.15–0.2 | ~15–20% | +| LOD3 | 0.05 | ~5% | + + +### textures + +:::danger +**Never** embed textures inside the .blend, keep them as sidecar files so they can be updated without opening Blender +::: + +This is the procedure to manage textures: + +**When adding a texture the first time**, in the Shader Editor, add an *Image Texture* node → click *Open* → navigate to your `assets_blender/.../` folder and select the `.png` file there. Blender will store a relative path automatically as long as the `.blend` has already been saved once alongside the textures. + +**Check a texture is external (not packed)**: look at the Image Texture node header. If you see a small floppy disk icon with a dot on it, the image is packed. If it shows just the filename, it's external. + +**To unpack an already-packed texture:** + +1. Go to *File* → *External Data* → *Unpack Resources* +2. Choose *"Write files to current directory"* (this places them next to the `.blend`) +3. Then move them to your proper `assets_blender/…/` folder and re-link (see [Files Structure page](../files_structure)) + +**To re-link a texture after moving it:** In the Image Texture node, click the folder icon next to the image name → navigate to the new path. Or use *File* → *External Data* → *Find Missing Files* to bulk-fix broken paths across all materials at once. + +**Make all paths relative** (important for team/version control): go to *File* → *External Data* → *Make All Paths Relative*. This converts all absolute `/home/you/project/...` paths to `//relative/...` paths, so the `.blend` works on any machine as long as the folder structure is preserved. + +The simplest rule: **textures live in the same folder as their `.blend`, or in a subfolder of it**. For your structure that means: + +- assets_blender/structures/buildings/houses/ + - house_colonial_2f.blend + - tex_house_colonial_2f_albedo.png + - tex_house_colonial_2f_normal.png + - tex_house_colonial_2f_roughness.png + + +### Export to Godot + +Once finished, export for Godot. + +**`File > Export > glTF 2.0 (.glb/.gltf)`** + +Choose the format **glTF Binary (`.glb`)** (single file, everything packed in. Best for most use cases). + + +This is the recommended Settings Panel: + +#### 🔵 Include + +| Option | Setting | +|---|---| +| **Limit to** | Selected Objects (if you don't want the whole scene) | +| **Data > Mesh** | ✅ UVs, Normals, Vertex Colors | +| **Data > Armature** | ✅ Export Deformation Bones Only | +| **Data > Skinning** | ✅ Enable | + +If your model contains blend shapes (shape keys / morph targets), the **Data > Armature > Export Deformation Bones Only** option must be enabled — exporting non-deforming bones will lead to incorrect shading in Godot. + + +#### 🟢 Transform + +| Option | Setting | +|---|---| +| **+Y Up** | ✅ **Enable this** — Godot uses Y-up, Blender uses Z-up | + +You can check **Transform > +Y Up** and other options from the built-in glTF exporter panel. + +#### 🟡 Geometry / Mesh + +| Option | Setting | +|---|---| +| **Apply Modifiers** | ✅ Enable (bakes modifiers into the mesh) | +| **Normals** | ✅ Enable | +| **UVs** | ✅ Enable | +| **Vertex Colors** | ✅ if used | +| **Compression (Draco)** | ❌ Avoid — Godot doesn't support Draco decompression natively | + + +#### 🟠 Animation (if exporting animated objects) + +| Option | Setting | +|---|---| +| **Animation** | ✅ Enable | +| **Export NLA Strips** | ✅ Enable — this separates animations by name in Godot | +| **Bake Animation** | ✅ Enable if you have complex drivers or constraints | +| **Sampling Rate** | 1 (default is fine) | +| **Optimize Animation** | ✅ Recommended | + +When exporting with animations, use **NLA Strips** mode — each strip in the NLA Editor becomes a separately named animation track in Godot, which is what allows the AnimationPlayer to recognize them individually. + + +#### 🔴 Before Exporting — Critical Checklist + +1. **Apply all transforms** (`Ctrl+A > All Transforms`) on both mesh and armature. Incorrect scale or rotation on an armature is the #1 cause of weird deformation issues in-engine. +2. **Check origin points** — objects floating in Godot is often caused by a misplaced origin in Blender. +3. **Materials**: Use **Principled BSDF** nodes. The exporter supports Metal/Rough PBR (core glTF) and Shadeless (KHR_materials_unlit) materials, and constructs a glTF material based on the nodes it recognizes in the Blender material. +4. **Textures** must be in PNG or JPEG format — other formats are auto-converted on export. + +#### Tip: Save as Export Preset + +Once you've configured everything, click the **➕ operator preset button** at the top of the export panel to save these settings as a reusable preset (e.g., "Godot Export"). This avoids reconfiguring every time. + + +## Import in Godot + +Once 3d model exported, open godot, you will have the file with extension *.glb*. + +Open it, and you will have the import window. + +On *Scene*, be sure to uncheck *Generate LODs*. + +On each MeshInstance3D with the suffix *_LOD0*, *_LOD1*, *_LOD2* and *_LOD3*, set the right fields (*Visibility Range Begin* and *Visibility Range End*): + +| Category | Examples | LOD0 | LOD1 | LOD2 | LOD3 | +|----------|----------|------|------|------|------| +| **Tiny** | coins, bolts, leaves | 0–0.5m | 0.5–2m | 2–5m | 5-8m | +| **Small** | cups, rocks, bottles | 0–1m | 1–5m | 5–15m | 15-25m | +| **Medium** | chairs, barrels, crates | 0–5m | 5–20m | 20–50m | 50-80m | +| **Large** | cars, trees, statues | 0–15m | 15–40m | 40–80m | 80-150m | +| **Huge** | buildings, terrain chunks | 0–30m | 30–80m | 80–200m | 200-400m | +| **Massive** | mountains, skybox elements | 0–100m | 100–300m | 300–800m | 800-1500m | + +Then click on *Import* or *Reimport* button. + + +**Practical Tips** + +- **Transparent / alpha objects** (leaves, fences) switch to a **flat billboard** at LOD2 or LOD3 diff --git a/docs/creativeConcept/files_structure.md b/docs/creativeConcept/files_structure.md new file mode 100644 index 0000000..503a355 --- /dev/null +++ b/docs/creativeConcept/files_structure.md @@ -0,0 +1,212 @@ +--- +title: Files structure +sidebar_position: 2 +--- + +# Folders and files organisation + +All files will be set in the [main / game repository](https://github.com/DyingStar-game/DyingStar). + + +## Organisation for game + +Inside we have 3D blender exported models (gltf files), textures... + +``` +- assets/ + - _universe/ + - environment/ + - space/ + - stations/ + - station_orbital_elevator_base.glb + - station_orbital_elevator_base.tresmaterial + - asteroids/ + - terrain/ + - rocks/ + - cliffs/ + - structures/ + - megastructures/ + - megastr_orbital_elevator_cable.glb + - megastr_orbital_elevator_anchor.glb + - industrial/ + - mines/ + - mine_entrance_large.glb + - mine_shaft_segment.glb + - refinery/ + - urban/ + - cities/ + - city_block_dense_a.glb + - villages/ + - village_house_rural_sm.glb + - buildings/ + - houses/ + - house_colonial_2f.glb + - props/ + - furniture/ + - furn_table_wood_lg.glb + - furn_chair_office.glb + - tools/ + - containers/ + - vehicles/ + - spaceship/ + - ship_freighter_class_a.glb + - ground/ + - characters/ + - humanoids/ + - creatures/ + - _shared/ + - materials/ + - shaders/ + - planets + - tarsis_4 + - structures/ + - buildings/ + - houses/ + - house_sandstone_dome.glb + - environment/ + - vegetation/ + - veg_tree_01.glb + - props/ + - containers/ + - prop_water_cistern_aridis.glb + - _shared/ + - materials/ +- scenes + - _universe/ + - environment/ + - space/ + - stations/ + - station_orbital_elevator_base.tscn + - asteroids/ + - terrain/ + - rocks/ + - cliffs/ + - structures/ + - megastructures/ + - megastr_orbital_elevator.tscn + - industrial/ + - mines/ + - mine.tscn + - refinery/ + - urban/ + - cities/ + - city_block_dense_a.tscn + - villages/ + - village_house_rural_sm.tscn + - buildings/ + - houses/ + - house_colonial_2f.tscn + - props/ + - furniture/ + - furn_table.tscn + - furn_chair.tscn + - tools/ + - containers/ + - vehicles/ + - spaceship/ + - ship_freighter_class_a.tscn + - ground/ + - characters/ + - humanoids/ + - creatures/ + - planet + - biome_xxx + - planet_data.gd + - systems + - tarsis + - tarsis_4.tscn + - tarsis_4 + - structures/ + - buildings/ + - houses/ + - house_sandstone_dome.tscn + - environment/ + - vegetation/ + - veg_tree_01.tscn + - props/ + - containers/ + - prop_water_cistern_aridis.tscn +- server +- test +``` + + +## Organisation for Blender files + +``` +- assets_blender/ + - _wip/ (for models not yet ready to export) + - _universe/ + - environment/ + - space/ + - stations/ + - station_orbital_elevator_base.blend + - tex_station_orbital_elevator_base_albedo.png + - tex_station_orbital_elevator_base_normal.png + - asteroids/ + - terrain/ + - rocks/ + - cliffs/ + - structures/ + - megastructures/ + - megastr_orbital_elevator_cable.blend + - megastr_orbital_elevator_anchor.blend + - industrial/ + - mines/ + - mine_entrance_large.blend + - mine_shaft_segment.blend + - refinery/ + - urban/ + - cities/ + - city_block_dense_a.blend + - villages/ + - village_house_rural_sm.blend + - buildings/ + - houses/ + - house_colonial_2f.blend + - props/ + - furniture/ + - furn_table_wood_lg.blend + - furn_chair_office.blend + - tools/ + - containers/ + - vehicles/ + - spaceship/ + - ship_freighter_class_a.blend + - ground/ + - characters/ + - humanoids/ + - creatures/ + - _shared/ + - materials/ + - hdri/ + - planets/ + - tarsis_4/ + - structures/ + - buildings/ + - houses/ + - house_sandstone_dome.blend + - environment/ + - vegetation/ + - veg_tree_01.blend + - props/ + - containers/ + - prop_water_cistern_aridis.blend + - _shared/ + - materials/ +``` + +## Naming convention + +The pattern is: [category_prefix]_[descriptor]_[variant/size].[ext] + +| Part | Rule | Examples | +| ---- | ---- | -------- | +| Category prefix | Short noun identifying the type | ship_, mine_, furn_, megastr_, city_, village_, house_, char_ | +| Descriptor | snake_case, most specific noun first | freighter_class_a, entrance_large, table_wood_lg | +| Variant/size | Optional suffix: sm/md/lg, a/b/c, v2, damaged | _sm, _a, _damaged | +| Extension | .blend in source, .glb + optional .tscn/.tres in Godot | — | + + + + diff --git a/docs/creativeConcept/static_files/blender_display_statistics.png b/docs/creativeConcept/static_files/blender_display_statistics.png new file mode 100644 index 0000000..b31f889 Binary files /dev/null and b/docs/creativeConcept/static_files/blender_display_statistics.png differ diff --git a/docs/creativeConcept/static_files/blender_viewport_overlays.png b/docs/creativeConcept/static_files/blender_viewport_overlays.png new file mode 100644 index 0000000..1f80997 Binary files /dev/null and b/docs/creativeConcept/static_files/blender_viewport_overlays.png differ