MVP Требования К Воксельному Движку

Цель MVP

Собрать минимальный воксельный runtime для Godot 4, в котором игрок может видеть, разрушать и изменять физически осмысленный мир из маленьких вокселей. MVP не должен быть «полной песочницей», но должен доказать, что базовая модель выдержит поздние системы Pepemoss: мох, жидкости, газы, конструкции, добычу, прочность материалов и автоматизацию.

Выбранный стек:

• Godot 4: окно, сцена, камера, ввод, UI, материалы, шейдеры, debug overlay, игровые объекты.
• Rust: хранение мира, чанки, симуляция, генерация мешей, физические запросы, сохранение.
• GDExtension: тонкий мост между Godot и Rust runtime.

Масштаб И Единицы

• Размер одного вокселя: 1 м / 16 = 0.0625 м, то есть 6.25 см.
• Один метр мира содержит 16 вокселей по каждой оси.
• Один кубический метр содержит 4096 вокселей.
• Рекомендуемый размер чанка для MVP: 32x32x32 вокселя, то есть 2x2x2 м.
• Координаты мира должны храниться как целочисленные voxel coordinates, а Godot-позиции вычисляться через масштаб 0.0625.

Граница Godot И Rust

Godot не должен напрямую владеть вокселями. Он должен получать от Rust готовые меши чанков, collision shape для активной области и API для запросов: луч, установка вокселя, разрушение, получить материал, получить debug-данные симуляции.

Базовая Модель Вокселя

MVP-воксель должен быть маленьким и дешёвым. Детальные свойства нельзя хранить в каждом вокселе.

Минимальные данные в ячейке:

• material_id: ID материала или air.
• substance: тип содержимого: solid, water, gas, empty.
• amount: заполненность для воды/газа, например 0..255.
• flags: dirty/sleeping/source/boundary, если нужно.

Свойства материала хранятся в MaterialRegistry:

• density: плотность.
• hardness: сопротивление инструменту и истиранию.
• elasticity: способность вернуть форму или поглотить удар.
• strength: предел разрушения.
• cohesion: связь с соседними вокселями.
• friction: трение для обвалов и контактов.
• porosity: способность пропускать газ/воду.
• render: ссылка на визуальный материал/текстуру.

Требование 1: Твёрдотельные Неподвижные Воксели

MVP не симулирует каждый твёрдый воксель как rigid body. Твёрдое вещество является статическим полем, пока не произошло редактирование, разрушение или обвал.

Требования:

• Чанк хранит плотный массив вокселей.
• Пустые/однородные чанки должны иметь оптимизацию, но не в первой версии.
• Редактирование одного вокселя помечает dirty текущий чанк и соседние чанки на границах.
• Мешинг для MVP: greedy meshing по кубическим поверхностям.
• Коллизия для MVP: collision mesh по тем же видимым поверхностям или упрощённый grid collider для активных чанков.
• Нужен API get_voxel, set_voxel, remove_voxel, raycast_voxel.

Не входит в MVP:

• Подвижные твёрдые voxel bodies.
• Сложные формы через marching cubes.
• Конструкции из отдельных физических блоков.

Требование 2: Симуляция Воды

Вода в MVP должна быть дискретной клеточной симуляцией, а не полноценной гидродинамикой. Цель: вода течёт вниз, растекается в стороны, заполняет ямы, может вытекать из разрушенного резервуара.

Модель:

• Водный воксель хранит amount от 0 до 255.
• Вода пытается перейти вниз, затем в стороны.
• Давление моделируется упрощённо через разницу заполненности между соседями.
• Обновляется не весь мир, а active set водных ячеек.
• Если вода пришла в соседний чанк, оба чанка получают simulation dirty flag.

Минимальные правила:

1. Если снизу empty или не полностью заполненная вода, вода течёт вниз.
2. Если вниз нельзя, вода распределяется по горизонтальным соседям.
3. Если ячейка стала стабильной, она засыпает до изменения соседей.
4. Твёрдый непористый материал блокирует воду.
5. Пористость материала может быть добавлена позже, но поле porosity уже должно быть в модели материала.

Визуализация:

• Для MVP можно рендерить воду отдельным transparent mesh на уровне чанка.
• Не требовать гладкой поверхности в первой версии.
• Важнее корректная симуляция и стабильность, чем красота.

Требование 3: Симуляция Газа

Газ похож на воду, но должен стремиться расширяться и выравнивать давление. Для Pepemoss это важно под будущие кислород, CO2, токсичные испарения, горение, вентиляцию и биомы.

Модель:

• Газовый воксель хранит gas_id и amount.
• В MVP в одной ячейке допускается только один тип газа.
• Газ распространяется в соседние пустые или газовые ячейки.
• Газ может подниматься вверх, если он легче воздуха, или опускаться, если тяжелее.
• Давление считается локально по amount.

Минимальные правила:

1. Газ выравнивает количество с соседями.
2. Газ проходит через пустоту.
3. Газ блокируется твёрдым непористым материалом.
4. Газ может вытесняться водой.
5. Очень маленькие количества газа исчезают или округляются, чтобы не плодить бесконечные микросостояния.

Не входит в MVP:

• Смешивание нескольких газов в одной ячейке.
• Температура и химические реакции.
• Реалистичная аэродинамика.

Требование 4: Гравитация

Гравитация в MVP нужна не для движения каждого вокселя, а для проверки устойчивости твёрдых массивов, падения воды и направления обвалов.

Требования:

• Направление гравитации фиксировано: -Y.
• Жидкости всегда предпочитают движение вниз.
• Газ может иметь собственную плавучесть относительно гравитации.
• Твёрдые воксели считаются стабильными, если они связаны с опорой через достаточно прочный путь.
• После разрушения вокселя запускается локальная проверка устойчивости вокруг места изменения.

Для MVP достаточно простой модели связности:

1. Найти соседние твёрдые компоненты после удаления вокселя.
2. Проверить, есть ли связь с землёй, границей чанка или заранее помеченной опорой.
3. Если связи нет, компонент считается нестабильным.
4. Нестабильный компонент в MVP можно либо удалить как обвал с эффектом, либо превратить в упрощённый падающий debris object.

Требование 5: Разрушаемость

Разрушение должно зависеть не от одного hp, а от физических свойств материала. Но MVP должен оставить модель простой.

Материал имеет:

• hardness: насколько трудно начать разрушение инструментом.
• elasticity: сколько энергии удара материал поглощает без повреждения.
• strength: сколько накопленного напряжения выдерживает.
• cohesion: насколько сильно материал держится за соседние воксели.
• density: влияет на массу обваливающихся компонентов.

Инструмент или воздействие создаёт damage_event:

• позиция;
• радиус;
• энергия;
• тип воздействия: удар, резание, бурение, взрыв, химия;
• направление.

MVP-формула может быть грубой:

effective_damage = max(0, energy - hardness - elasticity_absorption)
stress += effective_damage
destroy if stress > strength

Требования:

• Разрушение одного вокселя должно будить воду, газ и устойчивость соседей.
• У материала должна быть возможность сопротивляться конкретному типу воздействия.
• Накопленный stress лучше хранить не для всех вокселей, а только в sparse damage map для повреждённых ячеек.
• После разрушения надо пересобрать меш и коллизию только затронутых чанков.

Чанки И Обновления

Рекомендуемый MVP-пайплайн:

Очереди должны быть разделены:

• edit_queue: действия игрока и инструментов.
• simulation_queue: вода, газ, устойчивость.
• mesh_queue: пересборка геометрии.
• godot_upload_queue: передача результата в Godot main thread.

Минимальный API Rust Runtime

Godot-слою нужны такие операции:

• create_world(seed, config).
• load_chunk(chunk_coord).
• unload_chunk(chunk_coord).
• get_voxel(voxel_coord).
• set_voxel(voxel_coord, material_id).
• remove_voxel(voxel_coord, damage_event).
• raycast_voxel(origin, direction, max_distance).
• step_simulation(delta_time, budget).
• take_mesh_updates().
• take_debug_stats().

Важно: step_simulation должен принимать budget. Нельзя позволять воде или газу съесть весь кадр.

Критерии Готовности MVP

MVP можно считать готовым, если:

1. Godot показывает воксельный мир в масштабе 6.25 см на воксель.
2. Игрок может удалить и поставить твёрдый воксель.
3. Меш пересобирается локально, без полной перегенерации мира.
4. Вода вытекает из резервуара, падает вниз и заполняет яму.
5. Газ распространяется по пустому объёму и выравнивает давление.
6. Разрушение опоры вызывает локальную проверку устойчивости.
7. Материалы отличаются по твёрдости, упругости и прочности.
8. Runtime не блокирует кадр при небольшой активной симуляции.
9. Мир можно сохранить как seed + изменения + активное состояние воды/газа.

Что Не Делать В MVP

• Не делать бесконечно универсальный формат материалов.
• Не делать реалистичную CFD-симуляцию воды и газа.
• Не делать полноценные rigid body конструкции из вокселей.
• Не делать гладкий terrain до стабильного кубического greedy meshing.
• Не смешивать игровой рецепт пропов с низкоуровневым voxel storage.
• Не оптимизировать под огромный мир до появления стабильного маленького тестового полигона.

Следующий Документ

После этого MVP-документа нужен отдельный технический RFC по структуре Rust crate:

• pepemoss_voxel_core: чистая логика без Godot.
• pepemoss_voxel_godot: GDExtension-обёртка.
• pepemoss_voxel_tests: тесты симуляции воды, газа, разрушения и устойчивости.