# ccompass

This minetest mod adds a calibratable compass to the minetest. Original mod here

• License: Code: MIT, textures: CC BY-SA, sound: CC0.
• Dependencies to other mods: none
• Forum: https://forum.minetest.net/viewtopic.php?f=9&t=17881

For Players:

<TODO: nice screenshot>

1. Craft the compass as before using the crafting recipe. The new compass points to the origin / Zero point and is already usable.
2. Punch the compass to a compatible node (all by default) and enter the target name
3. Now this compass leads you allways to this location. You can give it away to allow other users to find this place.
4. Punch a teleport compatible node (by default mese block) to teleport back to the calibrated place

Depending on servers many aspects can be different, see below.

For server owners:

The mod support the next settings:

static_spawnpoint - use this position instead 0,0,0 as initial target
ccompass_recalibrate (enabled by default): If disabled each compass can be calibrated one time only
ccompass_restrict_target (Disabled by default): If enabled, only specific nodes are allowed for calibration (usable with any type waypoint nodes for example)
ccompass_restrict_target_nodes: List of technical node names allowed for compass calibration, separated by ','
ccompass_aliasses: If enabled the compas:* items will be aliased to the ccompass:* items for compatibility
ccompass_teleport_nodes: List of technical node names that triggers the teleport to destination, separated by ','. Default is "default:mese". Set it to "none" to disable the teleporting feature.
ccompass_nodes_over_target_allow: List of additional node names that must be above target for teleport to be executed. (separated by ',')
ccompass_nodes_over_target_deny: List of additional node names that must NOT be above target for teleport to be executed. (separated by ',')
ccompass_nodes_over_target_allow_drawtypes: List of drawtypes to allow to be over target. Defaults are: airlike, flowingliquid, liquid, plantlike and plantlike_rooted
ccompass_deny_climbable_target: Disabled by default -> allows climbable nodes to be over target. Set to true to not allow them.
ccompass_allow_damage_target: Disabled by default -> will not teleport player into or over damaging nodes.
ccompass_stack_max: 1 by default. Sets maximum stack size, 1 to 65535
ccompass_allow_using_stacks: Disabled by default -> calibrating and teleporting only works when single compass in hand. Setting to true, allows callibrating stacks to same location.
ccompass_idle_interval: 1 by default. When no players have active compasses, the mod enters an idle state and only checks for compasses at this interval, measured in seconds. This setting is meant to reduce the load on the server.

For developers:

1. It is possible to change compass settings from other mods by changing values in global table ccompass. So it is possible for example to add a waypoint node to the target-nodes by

	ccompass.recalibrate = true
	ccompass.restrict_target = true
	ccompass.restrict_target_nodes["schnitzeljagd:waypoint"] = true
	ccompass.teleport_nodes["default:diamondblock"] = true
	ccompass.nodes_over_target_allow["vacuum:vacuum"] = true
	ccompass.nodes_over_target_deny["tnt:boom"] = true
	ccompass.nodes_over_target_allow_drawtypes["liquid"] = nil
	ccompass.allow_climbable_target = false
	ccompass.allow_damaging_target = true
	ccompass.allow_using_stacks = true
	ccompass.stack_max = 42
	ccompass.idle_interval = 0

Also you can override ccompass.is_safe_target(target, nodename) for more granular checks. By default first nodes_over_target_allow is checked, then nodes_over_target_deny and finally nodes are checked for damaging and airlike drawtype.

Similarly you can override ccompass.is_safe_target_under(target, nodename) for more granular checks on what is under players feet.

2. The pointed node metadata will be checked for "waypoint_name" attribute. It this attribute is set, the calibration screen take this string as proposal. This can be used for a game specific calibration node. To get it working working just set in node definition something like

          after_place_node = function(pos, placer)
             local meta = minetest.get_meta(pos)
             meta:set_string("waypoint_name", "the unique and wunderfull place")
             meta:set_string("waypoint_pos", minetest.pos_to_string(target_pos)) -- if an other position should be the target instead of the node position
             meta:set_string("waypoint_skip_namechange", "skip") -- do not ask for the waypoint name
          end,

3. It is possible to create pre-calibrated compasses through other mods. Just write the position to the Itemstack meta:

    stack:get_meta():set_string("target_pos", minetest.pos_to_string(pos))

Recalibration related to a user should be done by function call

    local stack = ItemStack("ccompass:0")
    ccompass.set_target(stack, {
             target_pos_string = minetest.pos_to_string(pos),
             target_name = waypoint_name,
             playername = player:get_player_name()
    })

4. Each time the compass is updated, a hook is called, if defined in other mod. The hook is usefull to implement wear or any other compass manipulation logic.

    function ccompass.usage_hook(compass_stack, player)
        --do anything with compass_stack
        return modified_compass_stack
    end

5. Setting ccompass.stack_max to 1 restores behaviour prior to stackable feature. Or going the other way: set ccompass.stack_max to 777 and also set ccompass.allow_using_stacks to true. This would allow players to make a big number of copies at once.