20395524465

Committed 20 Dec 2025 02:11PM UTC coverage: 62.297% (-0.5%) from 62.793%

Build # 20395524465

Build Type

push

github

Committed by

tyevco

Commit Message

Add voxel game sample with biome-based terrain generation

This sample demonstrates how to build a voxel-based game using KeenEyes ECS:

- Chunk-based world storage with 16x16x16 voxel chunks
- Simplex noise terrain generation with multiple biomes
  (Plains, Forest, Desert, Mountains, Tundra, Ocean)
- Temperature and moisture-based biome selection
- Feature placement (trees, cacti, plants) using deterministic noise
- Player movement with AABB collision against voxel terrain
- Chunk loading/unloading based on player view distance
- ASCII side-view visualization for terminal output

Key architecture patterns shown:
- Complex component types (VoxelData, HeightMap) using IComponent directly
- System dependencies via property injection
- Seeded procedural generation for reproducible worlds
- Chunk coordinate to world coordinate transformations

Coverage Stats

2719 of 3811 branches covered (71.35%)

Branch coverage included in aggregate %.

15597 of 25590 relevant lines covered (60.95%)

0.85 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

86.11

/src/KeenEyes.Debugging/MemoryTracker.cs

using KeenEyes.Capabilities;

namespace KeenEyes.Debugging;

/// <summary>
/// Tracks memory usage and provides detailed statistics about ECS memory consumption.
/// </summary>
/// <remarks>
/// <para>
/// The MemoryTracker provides convenient access to memory statistics
/// with additional formatting and reporting capabilities.
/// </para>
/// <para>
/// Memory estimates are approximations based on component sizes and entity counts. Actual
/// memory usage may vary due to internal data structures, padding, and CLR overhead.
/// </para>
/// </remarks>
/// <example>
/// <code>
/// var tracker = world.GetExtension&lt;MemoryTracker&gt;();
///
/// // Get overall memory stats
/// var stats = tracker.GetMemoryStats();
/// Console.WriteLine($"Total entities: {stats.EntitiesActive}");
/// Console.WriteLine($"Estimated bytes: {stats.EstimatedComponentBytes}");
///
/// // Print formatted report
/// Console.WriteLine(tracker.GetMemoryReport());
/// </code>
/// </example>
public sealed class MemoryTracker
{
    private readonly IStatisticsCapability statisticsCapability;

    /// <summary>
    /// Initializes a new instance of the <see cref="MemoryTracker"/> class.
    /// </summary>
    /// <param name="statisticsCapability">The statistics capability to use.</param>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="statisticsCapability"/> is null.</exception>
    public MemoryTracker(IStatisticsCapability statisticsCapability)
    {
        ArgumentNullException.ThrowIfNull(statisticsCapability);
        this.statisticsCapability = statisticsCapability;
    }

    /// <summary>
    /// Gets memory statistics for the world.
    /// </summary>
    /// <returns>Current memory statistics.</returns>
    public MemoryStats GetMemoryStats()
    {
        return statisticsCapability.GetMemoryStats();
    }

    /// <summary>
    /// Gets a formatted memory report as a string.
    /// </summary>
    /// <returns>A multi-line string containing formatted memory statistics.</returns>
    /// <remarks>
    /// This method is useful for logging or displaying memory information in a human-readable format.
    /// </remarks>
    public string GetMemoryReport()
    {
        var stats = GetMemoryStats();

        var report = new System.Text.StringBuilder();
        report.AppendLine("=== Memory Statistics ===");
        report.AppendLine($"Entities: {stats.EntitiesActive} active, {stats.EntitiesRecycled} recycled, {stats.EntitiesAllocated} total allocated");
        report.AppendLine($"Entity Recycling: {stats.EntityRecycleCount} reuses ({stats.RecycleEfficiency:F1}% efficiency)");
        report.AppendLine($"Archetypes: {stats.ArchetypeCount}");
        report.AppendLine($"Component Types: {stats.ComponentTypeCount}");
        report.AppendLine($"Systems: {stats.SystemCount}");
        report.AppendLine($"Estimated Component Memory: {FormatBytes(stats.EstimatedComponentBytes)}");
        report.AppendLine($"Query Cache: {stats.CachedQueryCount} queries, {stats.QueryCacheHitRate:F1}% hit rate");

        return report.ToString();
    }

    private static string FormatBytes(long bytes)
    {
        if (bytes < 1024)
        {
            return $"{bytes} bytes";
        }

        if (bytes < 1024 * 1024)
        {
            return $"{bytes / 1024.0:F2} KB";
        }

        if (bytes < 1024 * 1024 * 1024)
        {
            return $"{bytes / (1024.0 * 1024):F2} MB";
        }

        return $"{bytes / (1024.0 * 1024 * 1024):F2} GB";
    }
}

1	using KeenEyes.Capabilities;
2
3	namespace KeenEyes.Debugging;
4
5	/// <summary>
6	/// Tracks memory usage and provides detailed statistics about ECS memory consumption.
7	/// </summary>
8	/// <remarks>
9	/// <para>
10	/// The MemoryTracker provides convenient access to memory statistics
11	/// with additional formatting and reporting capabilities.
12	/// </para>
13	/// <para>
14	/// Memory estimates are approximations based on component sizes and entity counts. Actual
15	/// memory usage may vary due to internal data structures, padding, and CLR overhead.
16	/// </para>
17	/// </remarks>
18	/// <example>
19	/// <code>
20	/// var tracker = world.GetExtension<MemoryTracker>();
21	///
22	/// // Get overall memory stats
23	/// var stats = tracker.GetMemoryStats();
24	/// Console.WriteLine($"Total entities: {stats.EntitiesActive}");
25	/// Console.WriteLine($"Estimated bytes: {stats.EstimatedComponentBytes}");
26	///
27	/// // Print formatted report
28	/// Console.WriteLine(tracker.GetMemoryReport());
29	/// </code>
30	/// </example>
31	public sealed class MemoryTracker
32	{
33	private readonly IStatisticsCapability statisticsCapability;
34
35	/// <summary>
36	/// Initializes a new instance of the <see cref="MemoryTracker"/> class.
37	/// </summary>
38	/// <param name="statisticsCapability">The statistics capability to use.</param>
39	/// <exception cref="ArgumentNullException">Thrown when <paramref name="statisticsCapability"/> is null.</exception>
40	public MemoryTracker(IStatisticsCapability statisticsCapability)	1✔
41	{	1✔
42	ArgumentNullException.ThrowIfNull(statisticsCapability);	1✔
43	this.statisticsCapability = statisticsCapability;	1✔
44	}	1✔
45
46	/// <summary>
47	/// Gets memory statistics for the world.
48	/// </summary>
49	/// <returns>Current memory statistics.</returns>
50	public MemoryStats GetMemoryStats()
51	{	1✔
52	return statisticsCapability.GetMemoryStats();	1✔
53	}	1✔
54
55	/// <summary>
56	/// Gets a formatted memory report as a string.
57	/// </summary>
58	/// <returns>A multi-line string containing formatted memory statistics.</returns>
59	/// <remarks>
60	/// This method is useful for logging or displaying memory information in a human-readable format.
61	/// </remarks>
62	public string GetMemoryReport()
63	{	1✔
64	var stats = GetMemoryStats();	1✔
65
66	var report = new System.Text.StringBuilder();	1✔
67	report.AppendLine("=== Memory Statistics ===");	1✔
68	report.AppendLine($"Entities: {stats.EntitiesActive} active, {stats.EntitiesRecycled} recycled, {stats.EntitiesAllocated} total allocated");	1✔
69	report.AppendLine($"Entity Recycling: {stats.EntityRecycleCount} reuses ({stats.RecycleEfficiency:F1}% efficiency)");	1✔
70	report.AppendLine($"Archetypes: {stats.ArchetypeCount}");	1✔
71	report.AppendLine($"Component Types: {stats.ComponentTypeCount}");	1✔
72	report.AppendLine($"Systems: {stats.SystemCount}");	1✔
73	report.AppendLine($"Estimated Component Memory: {FormatBytes(stats.EstimatedComponentBytes)}");	1✔
74	report.AppendLine($"Query Cache: {stats.CachedQueryCount} queries, {stats.QueryCacheHitRate:F1}% hit rate");	1✔
75
76	return report.ToString();	1✔
77	}	1✔
78
79	private static string FormatBytes(long bytes)
80	{	1✔
81	if (bytes < 1024)	1✔
82	{	1✔
83	return $"{bytes} bytes";	1✔
84	}
85
86	if (bytes < 1024 * 1024)	1✔
87	{	1✔
88	return $"{bytes / 1024.0:F2} KB";	1✔
89	}
90
91	if (bytes < 1024 * 1024 * 1024)	×
92	{	×
93	return $"{bytes / (1024.0 * 1024):F2} MB";	×
94	}
95
96	return $"{bytes / (1024.0 * 1024 * 1024):F2} GB";	×
97	}	1✔
98	}

orion-ecs / keen-eye / 20395524465

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous