Coordinate Type

[dbrgn]

There are basically three ways to specify coordinates:

---

Use "flat" parameters

Examples:

• set_block(x, y, z, block_type)
• get_height(x, z)
• set_blocks(x1, y1, z1, x2, y2, z2, block_type)

Advantages:

• Very simple to understand.
• Only standard types (integers, or floats in the case of player.get_pos).

Disadvantages:

• May seem messy to software engineers. The target audience are beginners though.

Use n-tuples

Examples:

• set_block((x, y, z), block_type)
• get_height((x, z))
• set_blocks((x1, y1, z1), (x2, y2, z2), block_type)

Advantages:

• It's possible to have an object that refers to a position in space.
• Tuples are simpler than a custom vector type.
• Flexible: Can handle both 2D and 3D coordinates

Disadvantages:

• No methods are possible on the positions
• Things like the double parentheses in get_height((x, z)) can be hard to explain

Use vectors

These should probably not be called vectors, but instead something like Position or Location.

Additionally, unless we want to end up with very dynamic objects, there need to be at least two different types: Position2D and Position3D. See get_height(x, z) as an example where we work with 2D instead of 3D coords.

Advantages:

• Methods and transformations possible
• By software engineering / OOP standards the cleaner solution than non-typed objects

Disadvantages:

• Harder to explain for beginners
• You need to differentiate between different reference systems: 3D coordinates, XZ coordinates, maybe also XY coordinates.

---

Out of these three possibilities, I'd strongly argue for the first one (as already posted here). It's the easiest thing to understand by absolute beginners. And that's what we should aim for.

(If you know more advantages or disadvantages, post them and I'll add them to the comparison).

[ghickman]

I'm strongly in favour of flat parameters here.

[jvlomax]

I'm strongly in favour of vectors. Vectors are the standard in 3D games. The reason is that the Vector class has a lot of game related functions that make them easier to use (distance, movement, length, etc.). Vector are not any harder to use than flat parameters, you just have to access them through a class (x,y,z) vs (vector3.x, vector3.y, vector3.z). You don't have to differentiate between XZ/YZ/XY coordinates. You only use the part of the vector you need

[dbrgn]

Vectors are the standard in 3D games.

I fully agree about this. But a 12 year old that wants to create funny things in Minecraft doesn't care about these standards. He neither cares about vector transformations :)

Explaining that set_block(x, y, z, block_type) creates a block at the x, y, z coordinates with the specified type is easy. Explaining that you need to create an instance of the Vector class and then access its attributes via the dot notation is harder.

I will actually introduce the Minecraft Pi API to 8 kids between 12-14 years in October, and I'd consider classes and instances an unnecessary obstacle when trying to teach them the basic concepts of programming (like variables, loops and function calls).

Maybe we could make a position class with all those helper methods that can be used optionally, with a method like get_xyz which returns a 3-tuple that can be unpacked?

pos1 = Position(4, 4, 12)
pos2 = Position(5, 5, 18)
distance_vector = pos2 - pos1
x, y, z = distance_vector.get_xyz()
mc.player.move(x, y, z)

As another example, most developers prefer vector math over quaternions, even though quaternions make some 3d transformations much more easy and elegant. Vector math is preferred because it is easier to understand.

[jvlomax]

If we just rename vector3 to position and everyone is happy with that then, I'm all for it

When a user runs pos = mc.player.getPos() i find it easier to explain that pos is a vector3/position that has a x,y and z coord, than explaining that it returns an immutable tuple that can be accesed by index where pos[0] = x, pos[1] = y and pos[3] = z

| Explaining that you need to create an instance of the Vector class and then access its attributes via the dot notation is harder

But we need to explain mc = Minecraft(), mc.player.setPos(), mc.setBlock(x, y, z, blocks.WOOD) which already introduces those concepts

[doismellburning]

I would be very interested in feedback from people who've already experienced teaching this to children of varying ages.

I think data on "what we explain and what we gloss over" + "what they found conceptually nontrivial" would be both useful and unsurprising.

@bennuttall Would you be able to provide?

[bennuttall]

I fully agree about this. But a 12 year old that wants to create funny things in Minecraft doesn't care about these standards. He neither cares about vector transformations :)

👍

If we just rename vector3 to position and everyone is happy with that then, I'm all for it

For the sake of understanding the code, this is a huge improvement. However are you talking about changing it at namespace level? Would that break compatibility?

[dbrgn]

But we need to explain mc = Minecraft(), mc.player.setPos(), mc.setBlock(x, y, z, blocks.WOOD) which already introduces those concepts

Except for the main Minecraft instance, the user never needs to instantiate anything. He can consider dots just part of the function name, without knowing about namespaces.

When a user runs pos = mc.player.getPos() i find it easier to explain that pos is a vector3/position that has a x,y and z coord, than explaining that it returns an immutable tuple that can be accesed by index where pos[0] = x, pos[1] = y and pos[3] = z

That's a good argument though. And the Position object could be more straightforward to use if we consistently use only kwargs in the docs: Position(x=5, z=6).

For the sake of understanding the code, this is a huge improvement. However are you talking about changing it at namespace level? Would that break compatibility?

I'm not sure how much the vector class was used anyways. I'd just create a new module, without touching the old module in the compat layer.

[doismellburning]

@bennuttall

If we just rename vector3 to position and everyone is happy with that then, I'm all for it

For the sake of understanding the code, this is a huge improvement. However are you talking about changing it at namespace level? Would that break compatibility?

Changing yes, but with compatibility layers and hackery such that nothing should break :)

[jonathanfine]

I think it is very important that we consider use cases when designing the high-level API. In other words we have a range of programming tasks and we write solutions for them.

Existing code, as I did in #7, is a good starting point. There are I'm sure lots of examples available.

I also think it very important that we get advice from educators @bennuttall and if we can learn from experience with users.

We can also learn from prior art, such as Logo and Scratch. Designing the API is, I think, both hard and important. And I expect that we will have many disagreements before consensus emerges.

[pozorvlak]

It looks like in English schools, vectors are only introduced at Key Stage 4 (ages 14-16). No doubt quite a few kids will have encountered vectors before then, but if we're trying to make something that's useful for teaching we probably shouldn't depend on knowledge that the kids aren't supposed to have yet.