Touchscreen: Allow mods to swap the meaning of short and long taps (punch with single tap)

[grorp]

Currently, short tap is hardcoded as "place" and long tap is hardcoded as "dig". This PR allows mods to swap the meaning of short and long taps, depending on the wielded item and the pointed_thing type. This is done by adding a new field to item definitions:

touch_interaction = {
    -- Only affects Android clients.
    -- Defines the meaning of short and long taps with the item in hand.
    -- The fields in this table have two valid values:
    -- * "long_dig_short_place" (long tap  = dig, short tap = place)
    -- * "short_dig_long_place" (short tap = dig, long tap  = place)
    -- The field to be used is selected according to the current
    -- `pointed_thing`.

    pointed_nothing = "long_dig_short_place",
    pointed_node    = "long_dig_short_place",
    pointed_object  = "short_dig_long_place",
},

Although this is only a very limited amount of customizability, it already solves two important problems:

1. Items that require holding the place button can be made usable. Fixes Hold Interact on mobile #8543.

   A prime example of this are bows and crossbows in MineClone 2. They are currently completely unusable on Android because they must be drawn by holding the place button. With this PR, all you need to do is to add the following code to their item definitions:

   touch_interaction = {
       pointed_nothing = "short_dig_long_place",
       pointed_node    = "short_dig_long_place",
       pointed_object  = "short_dig_long_place",
   },

   And you have usable bows on Android!

2. It becomes possible to punch with short taps.

   Currently, you have to do a long tap to punch another player or an entity. This is very bad for combat, as you have to wait 500 ms each time you want to punch your opponent. During these 500 ms you can't change your look direction, so it's trivial for your opponent to dodge the punch. To make things even worse, you can't keep your finger on the screen to punch continously because of commit 94feb62.

   With this PR, you can make punching with short taps possible by adding the following code to item definitions:

   touch_interaction = {
       pointed_object = "short_dig_long_place",
   },

   This not only fixes the problems described above, but it is also the behavior that players know from popular games such as Minecraft and MultiCraft.

   Because of these advantages, this PR makes punching with short taps the default.

Alternatives

These problems could also be solved by adding separate on-screen buttons for placing and digging. I plan to implement that as another option at some point and have already created a prototype: #13229 (comment).

However, I think that touch controls without additional on-screen buttons can and should work as well, as they are easier to understand for beginners and can be quite comfortable if you aren't doing PvP.

To do

This PR is a Ready for Review.

Please give feedback on the concept, the API, the implementation, etc.!

How to test

Play a MineClone 2 world on your Android phone. Verify that you can now punch mobs with a short tap. Verify that the rest of the touch controls still works as usual and that bows are still unusable.

Now put the following code into a mod:

minetest.register_on_mods_loaded(function()
    for name in pairs(minetest.registered_items) do
        if name:find("bow") then
            minetest.override_item(name, {
                touch_interaction = {
                    pointed_nothing = "short_dig_long_place",
                    pointed_node    = "short_dig_long_place",
                    pointed_object  = "short_dig_long_place",
                },
            })
        end
    end
end)

Rejoin your world and see that bows have become usable.

[MisterE123]

What does "hint" mean? Is there some kind of textual hint that allows android players to know what to do? If so, that text should be customizable: e.g. Instead of the bows having a short_tap assigned to a "dig" textual hint, the mod should be able to set it to "draw bow".

[grorp]

What does "hint" mean? Is there some kind of textual hint that allows android players to know what to do? If so, that text should be customizable: e.g. Instead of the bows having a short_tap assigned to a "dig" textual hint, the mod should be able to set it to "draw bow".

No, there are no textual hints. If you think that players will need them, you can add them yourself, e.g. via item descriptions or HUDs.

Maybe the field should be named touch_controls instead of touch_control_hint.

[MisterE123]

Yes, that is less confusing.

[tetsuo55]

Very nice, works great.

Is it possible to also make the spyglass and rocket work?

Edit: got spyglass to work by adding the same code but with bow replaced by spyglass.

Rockets can't get working, I tried both variants but it just waves the rocket

[grorp]

Edit: got spyglass to work by adding the same code but with bow replaced by spyglass.

👍

Rockets can't get working, I tried both variants but it just waves the rocket

The MineClone 2 implementation of rockets only supports launching rockets while flying with an elytra: https://git.minetest.land/MineClone2/MineClone2/src/commit/d4797e13af1e6f7c6cf2806790e8d0a2be448e5d/mods/ITEMS/mcl_fireworks/register.lua#L12-L22

I suppose the rockets would still benefit from "short_dig_long_place".

[tetsuo55]

When doing the long press to charge a bow or zoom in with the spyglass I can't move to aim, is that expected?

Also the rocket worked too after I used it while flying (using the short_dig_long_place)

[grorp]

When doing the long press to charge a bow or zoom in with the spyglass I can't move to aim, is that expected?

Yes, that's unfortunately expected if you haven't enabled touch_use_crosshair. #11003

I recommend enabling touch_use_crosshair.

[tetsuo55]

Could you help with making the off hand shield work, with this change long pressing no longer raises it

[grorp]

Could you help with making the off hand shield work, with this change long pressing no longer raises it

I assume we're still talking about MineClone 2 or similar. According to my testing, there are two ways to use a shield in that game: in the main hand or in the off-hand. Both ways require holding the place button, so the shield can't possibly work on Android without this PR.

Modders can make the shield work in the main hand easily, using the same approach as for the bow. Making the shield work in the off-hand is more complicated. The only sane approaches I can think of are:

1. controls like the ones I proposed in Android: Add more touchscreen buttons #13229 (comment)
2. an additional, mod-defined on-screen button for the shield (would require a touch controls API for mods)

So this is outside the scope of this PR.

[ataberkw]

When I add touch_controls to bow, it spams throwing arrows instead of drawing the bow. Both with or without touch_use_crosshair. Is that expected or do i missed something?

touch_controls = {
    pointed_nothing = "short_dig_long_place",
    pointed_node    = "short_dig_long_place",
    pointed_object  = "short_dig_long_place",
},

[grorp]

When I add touch_controls to bow, it spams throwing arrows instead of drawing the bow. Both with or without touch_use_crosshair. Is that expected or do i missed something?

If we're still talking about MineClone 2 or similar: No, that's not expected. If we're talking about a different bow mod: I don't know, I'd need to know which one. Different bow mods have different controls, some don't require you to draw the bow first.

Make sure to add touch_controls to all variants of the bow item, not only to one variant.

[srifqi]

Can we use other name than touch-control hint? How about touch-control mechanic, touch-control action plan, or touch-control tap action?

[grorp]

Can we use other name than touch-control hint? How about touch-control mechanic, touch-control action plan, or touch-control tap action?

What I meant by "touch control hint" was that the field is a hint as to what touch controls might work for the item, given by modders to Minetest because Minetest can't figure it out on its own.

While I agree that the name is bad, I'm not convinced by any of these suggestions either, partly because they're all longer than the current name. Since this name is only internal, it probably doesn't matter much anyway.

We could just adopt the external name (touch_controls) for the internal name and call it TouchControls, but that would conflict with a potential rename of TouchScreenGUI to TouchControls.

[ataberkw]

When I add touch_controls to bow, it spams throwing arrows instead of drawing the bow. Both with or without touch_use_crosshair. Is that expected or do i missed something?

If we're still talking about MineClone 2 or similar: No, that's not expected. If we're talking about a different bow mod: I don't know, I'd need to know which one. Different bow mods have different controls, some don't require you to draw the bow first.

Make sure to add touch_controls to all variants of the bow item, not only to one variant.

Yes it's MineClone2 mcl_bows:bow bow.

-- Bow item, uncharged state
minetest.register_tool("mcl_bows:bow", {
	description = S("Bow"),
	_tt_help = S("Launches arrows"),
	_doc_items_longdesc = S("Bows are ranged weapons to shoot arrows at your foes.").."\n"..
S("The speed and damage of the arrow increases the longer you charge. The regular damage of the arrow is between 1 and 9. At full charge, there's also a 20% of a critical hit, dealing 10 damage instead."),
	_doc_items_usagehelp = S("To use the bow, you first need to have at least one arrow anywhere in your inventory (unless in Creative Mode). Hold down the right mouse button to charge, release to shoot."),
	_doc_items_durability = BOW_DURABILITY,
	inventory_image = "mcl_bows_bow.png",
	wield_scale = mcl_vars.tool_wield_scale,
	touch_controls = {
		pointed_nothing = "short_dig_long_place",
		pointed_node    = "short_dig_long_place",
		pointed_object  = "short_dig_long_place",
	},
	stack_max = 1,
	range = 4,
	-- Trick to disable digging as well
	on_use = function() return end,
	on_place = function(itemstack, player, pointed_thing)
		if pointed_thing and pointed_thing.type == "node" then
			-- Call on_rightclick if the pointed node defines it
			local node = minetest.get_node(pointed_thing.under)
			if player and not player:get_player_control().sneak then
				if minetest.registered_nodes[node.name] and minetest.registered_nodes[node.name].on_rightclick then
					return minetest.registered_nodes[node.name].on_rightclick(pointed_thing.under, node, player, itemstack) or itemstack
				end
			end
		end

		itemstack:get_meta():set_string("active", "true")
		return itemstack
	end,
	on_secondary_use = function(itemstack)
		itemstack:get_meta():set_string("active", "true")
		return itemstack
	end,
	groups = {weapon=1,weapon_ranged=1,bow=1,enchantability=1},
	_mcl_uses = 385,
})

[grorp]

Yes it's MineClone2 mcl_bows:bow bow.

You're only adding touch_controls to the uncharged variant of the bow item (see the comment at the beginning of the code section you posted). To make it work, you need to add touch_controls to the charged variant as well (search for -- Bow in charging state in the same file).

[grorp]

Rebased again because of the set_bone_position regression (#14141).

[sfan5]

Needs a rebase, feel free to merge afterwards.

[grorp]

I found two more bugs while rebasing, but now it should actually be ready to merge 😅