How does a nodebox work/What is a nodebox?

[Traxie21]

I have yet to understand nodeboxes.
I've experimented with other peoples mods, but it still makes no logical sense to me. I have checked the forums, but have not found a detailed enough explanation on what a nodebox is.

Could someone explain this mystery to me? (Maybe collision boxes too.)

[VanessaE]

A nodebox is just a box-shaped object within a node. Normally you include a few of them in your node to create the basic shape. First, imagine a square:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

|¯¯¯|
|___|


Now, mentally mark the bottom left corner:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

  |¯¯¯|
  |___|
[1]


This square is the front face of your nodebox, so it covers the X and Y dimensions Now extend the box into a 3d cube, i.e. the Z direction:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

     ___
   /   /|
  |¯¯¯| |
  |___|/
[1]


And mentally mark the diagonally-opposite corner at the back side of the cube:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

     ___[2]
   /   /|
  |¯¯¯| |
  |___|/
[1]


The dead center of the box is {0,0,0}. The left, bottom, and front-most sides of the box are the -X, -Y, and -Z sides, respectively. Any given direction extends from -0.5 to +0.5 (which is why 0 is in the middle). You can go past -/+ 0.5 if you want, but that'll cause it to encroach into neighboring nodes (Home Decor refrigerator does that), and textures may or may not tile properly, so stick to within those limits for now.

The format of a nodebox definition is {X1, Y1, Z1, X2, Y2, Z2} for corners 1 and 2 as described above.

So, you set the drawtype to "nodebox", then you include one or more of the above {X1,..Z2} bits above, for every piece you want to define, in this format:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

minetest.register_node('mymod:my_best_nodebox', {
        description = "My kickass nodebox object",
        tiles = {
          "top.jpg",
          "bottom.jpg",
          "left.jpg",
          "right.jpg",
          "front.jpg",
          "back.jpg",
        },
        -- [more of the usual register_node() stuff here]
        drawtype = "nodebox",
        node_box = {
                type = "fixed",
                fixed = {
                    {X1, Y1, Z1,  X2, Y2, Z2},
                    {X1, Y1, Z1,  X2, Y2, Z2},
                    {X1, Y1, Z1,  X2, Y2, Z2},
                    {X1, Y1, Z1,  X2, Y2, Z2},
                    -- for as many boxes as you want to include
                }
        },
})


The images you supply in the tiles parameter will effectively be projected onto the nodeboxes after they're created, so each face of a nodebox will receive the pixels from your image that would be at that location had this just been a normal, whole 1x1x1 cube. This is true for every nodebox you supply, even if it seems like one should cast a shadow on another, so you'll want to stick with solid objects or use textures that can apply equally well to all nodebox faces that point in a given direction. This is why the valves in Pipeworks have a shadow under the handle - because the texture is repeated onto the nodeboxes below the handle as well.

Essentially, it's the same format as a selection box, and typically, you'll want to include such a section in the node def as well, with suitable box dimensions, so that the user doesn't have to select the entire cube just for some tiny little object inside it.

Also, thou shalt worship my mad ASCII art skillz. ;-)

[prestidigitator]

A node box is a very simplistic 3D model. Simplistic in that you can create a union of simple rectangular prisms ("boxes"), and all the boxes in the model get their textures by projecting the faces of the full 1x1x1 node cube's faces onto their own sides (so if you put one box on top of the other, both their top faces will have the same color at the same (x, z) coordinate.

Node boxes are used for drawing the node and for collisions with players and physical Lua entities. Selection boxes are defined in the same way, but are used to determine what the player crosshairs are touching (using ray tracing I presume) and to display the outline of the currently selected node.

Collision boxes are used for both collisions and selections, but for entities (Lua entities and player entities) instead of nodes. The engine can't use the entity's full 3D mesh (would be too processor intensive for Minetest) or sprite to determine collisions, so the collision box gives a very simple box-based model for physics (and selection). This could possibly be automatically calculated from the max bounds of the mesh/sprite/visual_size, but it would give less control over the behavior. You might want to have an antenna sticking up out of an entity's model, but not consider it important enough to influence collisions or object selection.

EDIT: I'm slow, and VanessaE's answer is a lot more practical. Feel free to ignore my babbling. :-)

[prestidigitator]

It raises an interesting point though. Nodes with node boxes actually have a more detailed physical collision model than entities. Maybe entities should be able to define a list of boxes too instead of one simple bounding box. Hmm.

[Traxie21]

Wow, thanks a lot guys! I think it makes more sense now.
And yes Vanessa, awesome ASCII. If I understand correctly though, your example makes 4 boxes inside each other. Y/N?

[prestidigitator]

Why does the nodebox need paramtype = light?

THAT'S a good question. I believe it is a defect that any nodebox node without paramtype = "light" is rendered almost black, no matter what the lighting level. That's why they all have it, of course. I haven't tried to dig into the engine code to see why, but I may at some point.

[VanessaE]

Traxie: In the example code, there would be four boxes placed somewhere in the node, but where they would be and whether or not they overlap would be up to you, by plugging in suitable coordinates in place of the X1,...Z2 stuff I wrote. Each of those four lines describes an independent nodebox, with coordinates always being relative to the center of the whole node they're contained in.

Prestidigitator: It's because nodeboxes aren't lighted properly (they don't respond to smooth lighting and they don't generate shadows properly), but they don't turn really dark or anything - they just look out of place without that field.

[prestidigitator]

It's because nodeboxes aren't lighted properly (they don't respond to smooth lighting and they don't generate shadows properly), but they don't turn really dark or anything - they just look out of place without that field.

Oh. Huh. Every time I have created a nodebox style node, it has been rendered almost pitch black (if I look at my LCD at the right angle and maybe squint a little I can see just a hint of color) until I remember to set the "light" paramtype. That's at full noon out in the open, with all nodes around them lit as brightly as possible. With paramtype = "light", on the other hand, they glow in the dark a bit, even in the pitch dark of a deep cave at midnight.

[VanessaE]

Oh wait, you're right - I was mixing it up with the sunlight_propagates field.