openstranded_map_tool/

convert.rs

// openstranded-map-tool — convert Stranded II .s2 maps to .osmap format
// Copyright (C) 2026  OpenStranded contributors
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Convert parsed `.s2` data into the `.osmap` format.

use std::collections::HashMap;

use crate::types::*;

/// Convert a parsed `.s2` map into an `.osmap` (Bevy convention).
///
/// # Coordinate conversion
///
/// `.s2` stores positions in **Blitz3D convention**:
///   - origin at terrain corner (0..terrain_size in both X and Z)
///   - +Z forward
///
/// `.osmap` stores positions in **Bevy convention**:
///   - origin centered at the terrain centre
///   - −Z forward (Bevy standard)
///   - units = grid cells (same as .s2, i.e. one unit per terrain segment)
///
/// The engine scales grid-cell units to world units by multiplying with the
/// map's step factor (`step = 64.0 / terrain_size`).
pub fn s2_to_osmap(s2: S2Map, source_filename: &str) -> OpenStrandedMap {
    let terrain_size = s2.terrain_size;
    let half = terrain_size as f32 / 2.0;

    // ── Flip heightmap Z: row z → row (terrain_size - z) ────────────
    // This keeps entity height-sampling consistent after Z negation.
    let heights = flip_heightmap_z(&s2.heights, terrain_size);

    let terrain = TerrainData {
        size: terrain_size,
        heights,
        seaground_level: -2.0,
    };

    let colormap = if s2.colormap_dim > 0 {
        Some(ColormapData {
            dim: s2.colormap_dim,
            pixels: s2.colormap.clone(),
        })
    } else {
        None
    };

    let grass = if !s2.grass.is_empty() {
        Some(GrassData {
            dim: s2.colormap_dim + 1,
            values: s2.grass.clone(),
        })
    } else {
        None
    };

    // ── Convert entities ────────────────────────────────────────────
    // Position conversion from .s2 (Blitz3D) to .osmap (Bevy convention):
    //   osmap_x = s2_x - half
    //   osmap_z = half - s2_z     (center + negate Z for Bevy −Z-forward)
    //
    // For objects: Y is sampled from the FLIPPED heightmap (which we just
    // built) using ORIGINAL grid coordinates (s2_x, s2_z).  The original
    // heightmap index `[z * stride + x]` in the flipped array now stores
    // the height for grid position (x, terrain_size - z).  Since the
    // original s2_z value directly indexes the flipped array at the same
    // index (we only re-ordered rows, not the indexing convention),
    // sampling with original (s2_x, s2_z) into `heights[]` is correct:
    //   flipped[z * stride + x] = original[(terrain_size - z) * stride + x]
    //   sample(s2_x, s2_z) → heights[s2_z * stride + s2_x]
    //     = original[(terrain_size - s2_z) * stride + s2_x]
    //   Which is the height at grid (s2_x, terrain_size - s2_z).
    // The terrain mesh places vertex at grid_z in world-z, and the entity
    // at negated world-z sees the same height.  Internally consistent.
    let mut entities: Vec<MapEntity> = Vec::new();

    for obj in &s2.objects {
        // Sample using ORIGINAL .s2 coords (before centering/Z-negation)
        let y = sample_height(&terrain.heights, terrain_size, obj.x, obj.z);
        entities.push(MapEntity {
            class: "object".into(),
            type_id: obj.typ,
            id: obj.id,
            position: (obj.x - half, y, half - obj.z),
            rotation_yaw: deg_to_rad(obj.yaw),
            health: obj.health,
            health_max: obj.health_max,
            amount: 0,
            parent_id: 0,
            parent_class: 0,
            links: vec![],
            build_progress: 0,
            states: vec![],
            script: None,
            unit_data: None,
            extensions: extract_extensions_for_parent(&s2.extensions, 1, obj.id),
        });
    }

    for unit in &s2.units {
        entities.push(MapEntity {
            class: "unit".into(),
            type_id: unit.typ,
            id: unit.id,
            position: (unit.x - half, unit.y, half - unit.z),
            rotation_yaw: deg_to_rad(unit.yaw),
            health: unit.health,
            health_max: unit.health_max,
            amount: 0,
            parent_id: 0,
            parent_class: 0,
            links: vec![],
            build_progress: 0,
            states: vec![],
            script: None,
            unit_data: Some(UnitData {
                hunger: unit.hunger,
                thirst: unit.thirst,
                exhaustion: unit.exhaustion,
                ai_center_x: unit.ai_center_x - half,
                ai_center_z: half - unit.ai_center_z,
                day_timer: 0.0,
            }),
            extensions: extract_extensions_for_parent(&s2.extensions, 2, unit.id),
        });
    }

    for item in &s2.items {
        entities.push(MapEntity {
            class: "item".into(),
            type_id: item.typ,
            id: item.id,
            position: (item.x - half, item.y, half - item.z),
            rotation_yaw: deg_to_rad(item.yaw),
            health: item.health,
            health_max: 0.0,
            amount: item.count,
            parent_id: item.parent_id,
            parent_class: item.parent_class,
            links: vec![],
            build_progress: 0,
            states: vec![],
            script: None,
            unit_data: None,
            extensions: extract_extensions_for_parent(&s2.extensions, 3, item.id),
        });
    }

    for info in &s2.infos {
        entities.push(MapEntity {
            class: "info".into(),
            type_id: info.typ as u32,
            id: info.id,
            position: (info.x - half, info.y, half - info.z),
            rotation_yaw: deg_to_rad(info.yaw),
            health: 0.0,
            health_max: 0.0,
            amount: 0,
            parent_id: 0,
            parent_class: 0,
            links: vec![],
            build_progress: 0,
            states: vec![],
            script: Some(info.vars.clone()),
            unit_data: None,
            extensions: extract_extensions_for_parent(&s2.extensions, 4, info.id),
        });
    }

    // Build environment map
    let mut environment = HashMap::new();
    environment.insert("day".into(), s2.env_vars.day.to_string());
    environment.insert("hour".into(), s2.env_vars.hour.to_string());
    environment.insert("minute".into(), s2.env_vars.minute.to_string());
    environment.insert("freezetime".into(), s2.env_vars.freezetime.to_string());
    environment.insert("skybox".into(), s2.env_vars.skybox);
    environment.insert("multiplayer".into(), s2.env_vars.multiplayer.to_string());
    environment.insert("climate".into(), s2.env_vars.climate.to_string());
    environment.insert("music".into(), s2.env_vars.music);
    let briefing = s2.env_vars.briefing.clone();
    let decoded_pw = s2.password.decoded.clone();
    environment.insert("briefing".into(), s2.env_vars.briefing);
    environment.insert("fog_r".into(), s2.env_vars.fog[0].to_string());
    environment.insert("fog_g".into(), s2.env_vars.fog[1].to_string());
    environment.insert("fog_b".into(), s2.env_vars.fog[2].to_string());
    environment.insert("fog_mode".into(), s2.env_vars.fog[3].to_string());
    if !decoded_pw.is_empty() {
        environment.insert("password".into(), decoded_pw);
    }

    // Collect scripts from infos and briefing
    let mut scripts: Vec<ScriptData> = Vec::new();
    for info in &s2.infos {
        if !info.vars.is_empty() {
            scripts.push(ScriptData {
                text: info.vars.clone(),
                entity_id: info.id,
            });
        }
    }
    if !briefing.is_empty() {
        scripts.push(ScriptData {
            text: briefing,
            entity_id: 0,
        });
    }

    OpenStrandedMap {
        meta: MapMeta {
            name: source_filename.trim_end_matches(".s2").to_string(),
            engine_version: env!("CARGO_PKG_VERSION").to_string(),
            map_version: "0.2.0".to_string(),
            source_file: source_filename.to_string(),
            s2_header: Some(s2.header),
            created_at: String::new(),
        },
        terrain,
        entities,
        // Player spawn at terrain centre, Y=2.0 (placeholder — heightmap
        // sampling in the engine will override Y).  Already in Bevy
        // convention (centered, −Z forward).
        player_spawn: Some(PlayerSpawn {
            position: (0.0, 2.0, 0.0),
            rotation_yaw: 0.0,
        }),
        environment,
        colormap,
        grass,
        password: s2.password.decoded.clone(),
        scripts,
    }
}

/// Reverse the Z-axis order of a heightmap (row‑major `[z * stride + x]`).
///
/// Row `z` is moved to row `(terrain_size - z)`.  This is needed so that
/// the terrain mesh stays consistent when entity Z is negated (Bevy uses
/// −Z forward whereas the original Blitz3D uses +Z forward).
fn flip_heightmap_z(heights: &[f32], terrain_size: u32) -> Vec<f32> {
    let stride = (terrain_size + 1) as usize;
    let mut out = vec![0.0; heights.len()];
    for z in 0..=terrain_size as usize {
        for x in 0..stride {
            let src = z * stride + x;
            let dst = (terrain_size as usize - z) * stride + x;
            out[dst] = heights[src];
        }
    }
    out
}

/// Sample height from the heightmap at a given (x, z) world position.
fn sample_height(heights: &[f32], terrain_size: u32, x: f32, z: f32) -> f32 {
    if heights.is_empty() {
        return 0.0;
    }
    let size = terrain_size as f32;
    let ix = (x.clamp(0.0, size)).round() as usize;
    let iz = (z.clamp(0.0, size)).round() as usize;
    let idx = iz * (terrain_size as usize + 1) + ix;
    if idx < heights.len() {
        heights[idx]
    } else {
        0.0
    }
}

/// Convert degrees to radians.
fn deg_to_rad(deg: f32) -> f32 {
    deg * std::f32::consts::PI / 180.0
}

/// Extract extensions for a given parent class+id as key-value map.
fn extract_extensions_for_parent(
    extensions: &[S2Extension],
    parent_class: u8,
    parent_id: u32,
) -> HashMap<String, String> {
    let mut map = HashMap::new();
    for ext in extensions {
        if ext.parent_class == parent_class && ext.parent_id == parent_id {
            let key = if ext.key.is_empty() {
                format!("mode_{}", ext.mode)
            } else {
                ext.key.clone()
            };
            map.insert(key.clone(), ext.value.clone());
            if !ext.stuff.is_empty() {
                map.insert(format!("{}_stuff", key), ext.stuff.clone());
            }
        }
    }
    map
}