Block Properties refactor #2063

sebat2 · 2025-10-18T23:53:58Z

Summary

Implemented a sorted array system for rarely-used block properties, significantly reducing memory usage.

This is the first step toward addressing #1853.

Main changes

Added generic SortedBlockProperties<size, DataType> type with binary search for efficient access
Moved rarely-used properties (allowOres, gui, tickEvent, touchFunction, blockEntity) from full [65536] arrays to sorted arrays with ~100-300 entries
Organized all block properties into BlockProps structure for better code readability
Added helper functions isSortedProp() and resetSortedProperties() for automatic handling of sorted properties

Performance impact

Memory savings: ~5 properties × (65536 - 100) entries × type size ≈ 320 KB with current configuration, with potential for further optimization.

Access performance: O(log n) instead of O(1), but with n ≤ 300, the difference is negligible in practice.

Future work

Next steps for #1853:

Move most functions from block_entity.zig vtable to their own sorted BlockProps fields
Possibly remove block_entity entirely in favor of organizing entity blocks as separate files (one file per entity block type)

Also added .vscode and saves to .gitignore

Implemented a sorted array system for rarely-used block properties, significantly reducing memory usage. Main changes: - Added generic `SortedBlockProperties<size, DataType>` type with binary search for efficient access - Moved rarely-used properties (`allowOres`, `gui`, `tickEvent`, `touchFunction`, `blockEntity`) from full [65536] arrays to sorted arrays with ~100 entries - Organized all block properties into `BlockProps` structure for better code readability - Added helper functions `isSortedProp()` and `resetSortedProperties()` for automatic handling of sorted properties Memory savings: ~5 properties × (65536 - 100) entries × type size ≈ 320 KB with current configuration, with possibility for further optimization. Access performance: O(log n) instead of O(1), but n won't ever be higher than ~300, so the difference is negligible in practice. also added .vscode and saves to gitignore I want to work on refactoring block entities in a near future and this is the first part of it.

Removed excessive comments according to style guide.

I don't like some of the formatting rules tbh.

Argmaster · 2025-10-19T03:28:39Z

src/blocks.zig

+				return .gt;
+			}
+
+			pub fn getBlockSortedIdx(self: *const Self, blockId: u32) ?usize {


This doesn't need to be public.

Argmaster · 2025-10-19T03:31:24Z

.gitignore

 !/assets/backgrounds/default_background.png
 /assets/cubyz/music
 /assets/cubyz/fonts
+/saves/*


This should no longer be needed?
Also god damn that missing trailing lf

Argmaster · 2025-10-19T03:31:58Z

.gitignore

 zig-out/
 zig-cache/
 .zig-cache/
+.vscode/


IDE configurations are strictly forbidden from being mentioned anywhere in the repo.

@Argmaster I am sorry, what?

Can you link us to where that is written? I just checked CONTRIBUTING.md and I could not find anything related.

I hope you can see the ridiculousness of that statement. Because you are forbidden to add project configuration to repo, you are also forbidden to make git ignore it?

@psznm Exactly my thoughts on it.

Because you are forbidden to add project configuration to repo, you are also forbidden to make git ignore it?

It's pretty easy to do this yourself without adding it to gitignore, there is some more info here: #1851

It's pretty easy to do this yourself without adding it to gitignore, there is some more info here: #1851

That is nice. I didn't know that was even possible. It would be useful to copy the comment from zig .gitignore to this .gitignore.

Still, the statement @Argmaster made without any sort of explanation or suggestion really rubbed me the wrong way. I really think just a little bit more effort to help those who don't know goes a long way.

Yeah, @QuantumDeveloper we should include that in contribution guidelines. That was "knowledge of the elders" and I didn't exactly remember where to look for that discussion.

Argmaster · 2025-10-19T03:43:46Z

src/blocks.zig

+	/// with ~100-300 entries instead of creating arrays with maxBlockCount (65536) entries.
+	/// Magic Value - Increase it if you need to store more block properties.
+	/// Consider creating a separate variable with a comment for a specific property if only one needs a larger size.
+	pub const maxSortedBlockProperties: usize = 100;


Magic value is unfortunately unacceptable, as you don't know how many of them will be added by add-ons. I don't think the scale would be so huge that falling to array storage makes sense, but it should at least be resizeable to meet the demand in worst case scenario.

Argmaster · 2025-10-19T03:47:52Z

src/blocks.zig

+	/// Consider creating a separate variable with a comment for a specific property if only one needs a larger size.
+	pub const maxSortedBlockProperties: usize = 100;
+
+	pub var sortedAllowOres: SortedBlockProperties(maxSortedBlockProperties, bool) = .{};


The name is overqualified, it duplicates the information present in the type.

Argmaster · 2025-10-19T03:48:04Z

src/blocks.zig

+
+	pub var sortedAllowOres: SortedBlockProperties(maxSortedBlockProperties, bool) = .{};
+	// TODO: Tick event is accessed like a milion times for no reason. FIX IT
+	pub var sortedTickEvent: SortedBlockProperties(maxSortedBlockProperties, TickEvent) = .{};


The name is overqualified, it duplicates the information present in the type.

Argmaster · 2025-10-19T03:48:19Z

src/blocks.zig

+	pub var sortedAllowOres: SortedBlockProperties(maxSortedBlockProperties, bool) = .{};
+	// TODO: Tick event is accessed like a milion times for no reason. FIX IT
+	pub var sortedTickEvent: SortedBlockProperties(maxSortedBlockProperties, TickEvent) = .{};
+	pub var sortedTouchFunction: SortedBlockProperties(maxSortedBlockProperties, *const TouchFunction) = .{};


The name is overqualified, it duplicates the information present in the type.

Argmaster · 2025-10-19T03:48:37Z

src/blocks.zig

+	pub var sortedBlockEntity: SortedBlockProperties(maxSortedBlockProperties, *BlockEntityType) = .{};
+
+	/// GUI that is opened on click.
+	pub var sortedGui: SortedBlockProperties(maxSortedBlockProperties, []u8) = .{};


The name is overqualified, it duplicates the information present in the type.

Argmaster · 2025-10-19T03:49:38Z

src/blocks.zig

+	}
+}
+
+const BlockProps = struct {


What is the purpose of that struct?

Code organization. Grouping all block properties in one struct makes the code more readable than having them floating in the global namespace. Also, I'll probably make this struct public in later changes when I'm splitting most of the blocks.zig and block_entity.zig code into different files.

This is not C and those variables are not in the global namespace, but rather in the module scope of the module dedicated for this data. Following this relocation logic you should move all the methods in this file into that struct, as they are one big family and then the code would be equivalent to a file struct in a file struct. Files are from Zig perspective equivalent to structs.
Therefore past structure of this file should be interpreted as a struct with only static fields and static methods.

IntegratedQuantum

This adds a lot of complexity for saving 320 kiB (compare too the many gigabytes used by the rest of the game) while also likely degrading performance.
It would have to save at least 100× more memory to be even close to being reasonable.

For #1853 why not just use a single pointer per block type (ideally put into the BlockEntity struct) that points to the block entity data?

sebat2 · 2025-10-19T13:59:54Z

@IntegratedQuantum
The performance impact from binary search is extremely low, especially with low n values. Also, by using less memory we might fit more data into L1 cache, so I wouldn't worry about performance at all. For me the only downside is implementation complexity, but it makes adding new properties much less of an issue, which I need for #1853.

For #1853, I don't want to use the monolithic 'single pointer per block type' structure like we currently have for block entities. Instead, I want a more modular approach where each block can have unique functionality composed from smaller pieces.

My idea is to define block functionality in .zon files without hardcoding the block itself:

Example:

chest/_defaults.zig.zon

.{
    .tags = .{.choppable, .wood},
    .blockHealth = 10,
    .drops = .{
        .{.items = .{.auto}},
    },
    .model = "cubyz:cube",
    .rotation = "cubyz:planar",
    
    // Instead of .blockEntity = .chest, we use modular properties:
    .inventory = .{
        .size = 30,
        .type = .items  // Could be .blocks, .items, .energy, or .liquids (useful for mods)
    },
    .onInteract = .{
        .interact = .openInventory,
        .type = .items
    }
}

In this example, .inventory would automatically register all the functions it needs into BlockProps, but by itself it wouldn't allow opening the inventory. For that we'd use the .onInteract property. This way we can easily create new functional blocks by reusing existing code and combining different properties.

Argmaster · 2025-10-19T14:04:13Z

You cannot completely remove .blockEntity = chest because this part of the system must be moddable. Additionally you cannot define full list of params used by block entities, because the system has to be moddable.

There are some properties we will need in the future, eg. related to explosions but as of now there are only few we know about. Mods may require more, but your solution doesn't provide modding support for adding new props (past one didn't do that either)

Modding is different than add-ons - modding adds code, add-ons add assets.

sebat2 · 2025-10-19T14:09:00Z

I want to create a system where you can define new parameters in code and register them with the block_manager at startup, *( compile time #1528 ) so modding will be possible.

Argmaster · 2025-10-19T14:09:30Z

A way to save a bit of memory that was briefly considered was using ListUnmanaged, but the problem is that we are using Arena allocator, so that arena will aggregate unused memory on realloc, resulting in 1.5 memory usage compared to necessary capacity.

codemob-dev · 2025-10-19T14:10:08Z

I want to create a system where you can define new parameters in code and register
them with the block_manager at startup.

Check out rotation modes for how to do this kind of thing at compile-time.

sebat2 · 2025-10-19T14:10:53Z

k out rotation modes for how to do this kind of thing at compile-time.

Do we really want to compile mods with the game ?

codemob-dev · 2025-10-19T14:11:40Z

Yes, see #1528

sebat2 · 2025-10-19T14:19:09Z

Yes, see #1528

Ok, works for me, but overall this isn't really the subject of this review, so maybe we can talk about this when I start working on what I've proposed ;D ?

I know it has to support modding, so don't worry - I have that in mind.

Argmaster · 2025-10-19T14:25:54Z

Possibly remove block_entity entirely in favor of organizing entity blocks as separate files (one file per entity block type)

#1637

Argmaster · 2025-10-19T14:26:50Z

Move most functions from block_entity.zig vtable to their own sorted BlockProps fields

This would aggregate a lot of logic in one place and solves none of the problems with block entities we have now.

sebat2 added 3 commits October 19, 2025 01:26

Removed comments

39319ad

Removed excessive comments according to style guide.

Fixed formatting issues

df8e308

I don't like some of the formatting rules tbh.

Argmaster reviewed Oct 19, 2025

View reviewed changes

IntegratedQuantum requested changes Oct 19, 2025

View reviewed changes

sebat2 closed this Oct 19, 2025

Block Properties refactor #2063

Block Properties refactor #2063

Uh oh!

Conversation

sebat2 commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Main changes

Performance impact

Future work

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Argmaster Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sebat2 Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Argmaster Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum left a comment

Choose a reason for hiding this comment

Uh oh!

sebat2 commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

chest/_defaults.zig.zon

Uh oh!

Argmaster commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sebat2 commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Argmaster commented Oct 19, 2025

Uh oh!

codemob-dev commented Oct 19, 2025

Uh oh!

sebat2 commented Oct 19, 2025

Uh oh!

codemob-dev commented Oct 19, 2025

Uh oh!

sebat2 commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Argmaster commented Oct 19, 2025

Uh oh!

Argmaster commented Oct 19, 2025

Uh oh!

Reviewers

Assignees

Labels

sebat2 commented Oct 18, 2025 •

edited

Loading

Argmaster Oct 19, 2025 •

edited

Loading

sebat2 Oct 19, 2025 •

edited

Loading

Argmaster Oct 19, 2025 •

edited

Loading

sebat2 commented Oct 19, 2025 •

edited

Loading

Argmaster commented Oct 19, 2025 •

edited

Loading

sebat2 commented Oct 19, 2025 •

edited

Loading

sebat2 commented Oct 19, 2025 •

edited

Loading