doc

doc/design.txt

@@ -103,4 +103,78 @@ Data is freeform. Types 0...99 are reserved for initialization.
 Core uses cereal's portable binary serialization, except for low-level packet
 streaming.
 
+Voxels
+------
+A way to define voxel properties:
+- Polyvox can output about 2**23 = 8388608 different face materials (uint32_t ->
+  float conversion)
+- So given that each voxel has six faces, we can have about 8388608/6 =
+  1398101 (~2**20) different voxels
+- Pseudorandom selection of voxel textures doesn't lower this value; they
+  can be randomized at the texture coordinate generation phase (which are
+  generated from face materials at known positions in the mesh)
+- If voxels can be rotated, it directly lowers this value according to the
+  number of possible positions; if there are 4*6 rotational positions, we
+  can have 1398101/24 = 58254 different voxels
+- It probably doesn't make sense to distinguish rotation from voxel type in
+  volume data, which means the voxel type namespace size is 1398101
+- If a block spans multiple voxels, each of those is a distinct voxel type
+- This means that there can be 1398101/24/8 = 7281 distinct
+  rotatable 8-voxel blocks
+- A voxel instance only contains a 21-bit type id stored as the lowest bits
+  of an uint32_t; highest bits are reserved and should be ignored.
+- It is not possible to add game-specific data to voxels, but games can
+  utilize the 11 MSBs of the uint32_t
+	- Adding a field with a runtime-specified size is impossible in
+	  template-based PolyVox
+	- It is recommended that games only use the 8 MSBs. The rest 3 are
+	  reserved for future development of the engine.
+- In-memory storage:
+	- PolyVox::SimpleVolume<interface::VoxelInstance>
+	- Anything like PolyVox::LargeVolume isn't useful because the world will not
+	  be handled as a large contiguous space, but instead as many nodes that
+	  each contain a chunk of voxels. Custom-made in-memory compression can be
+	  added to them later and is not needed now. (Deinterlaced run-length
+	  encoding according to the most common block dimensions will probably work
+	  well.)
+- On-disk storage:
+	- Zlib is fine; probably a compression level of 6 is fine. Tests show that
+	  levels 1..3 perform poorly with this kind of data.
+- Special voxels are just regular voxels, but with a handler module name defined
+  as a property, into which the engine calls at construction and destruction
+  time, giving the generated node, voxel type id and position as parameters
+	- A torch could be similar to air, but the handler would create a child
+	  node with a model and a light at its position
+- Basic voxel types are defined by buildat:
+	- interface::VoxelName
+	- interface::VoxelTypeId (uint32_t)
+	- interface::VoxelDefinition
+	- interface::VoxelRegistry
+	- interface::VoxelInstance
+- The voxel world is handled by builtin/voxelworld on the server, and is built
+  in to the client. VoxelRegistry is part of builtin/voxelworld on the server.
+
+A way to define block properties:
+- interface::-based because the client has to support blocks directly:
+	- interface::BlockName (typedef ss_)
+	- interface::BlockTypeId (uint32_t)
+	- interface::BlockDefinition
+	- interface::BlockRegistry
+- Definitions refer to voxel definitions
+- In practice, voxel definitions are generated by definining a block that needs
+  them
+- Can be defined to be rotatable or not
+- Should there be an option to make a block rotatable only to 4 positions?
+- Saved volume data should be designed so that if a block's properties are
+  modified, it will not be invalidated; eg. if a block is changed to not be
+  rotatable and be of different voxel size, each of the voxels can be loaded
+  as their non-rotated counterparts as some suitable block segment
+	- This can be done by resolving IDs from namespaced names:
+	  "dirt;s=0,1,1;r=2;R=5"
+	- Or just have a VoxelName type which consists of these partitions
+	  (block_name, segment.{x,y,z}, rotation_primary, rotation_secondary)
+	- block_name: Name of the block this was instanced from
+	- segment.{x,y,z}: Which segment of the block this was instanced from
+	- rotation_primary: 4 possible rotations when looking at a face
+	- rotation_secondary: 6 possible directions for a face to point to
 

doc/todo.txt

@@ -25,13 +25,11 @@ Buildat TODO
 - Automatically fetch and build and patch Urho3D when building buildat
 - Handle module load order properly in reloads (unload by popping from top,
   then reload everything until top)
-- Try out dynamic geometry
 - Automatic buildat root detection so that the server and the client can
   generally be started with any working directory in either the in-source or
   windows-installed configuration
 - Precompiled mode
 - Singleplayer UI
-- Modules with no C++ code (eg. just a client-side library)
 - Show all exceptions and errors on client using ui_utils.show_message_dialog
 - Pass the replicated scene properly to Lua
 - Allow creating and destroying arbitrary amounts of replicated scenes