UpdateHint: create_if_not_exists (Allows clients to hint own items in other worlds)

MultiServer.py

@@ -1903,32 +1903,90 @@ async def process_client_cmd(ctx: Context, client: Client, args: dict):
 
         elif cmd == 'UpdateHint':
             location = args["location"]
-            player = args["player"]
-            status = args["status"]
-            if not isinstance(player, int) or not isinstance(location, int) \
-                    or (status is not None and not isinstance(status, int)):
+            location_player = args["player"]
+            create_if_not_exists = args.get("create_if_not_exists", False)
+            status_int = args.get("status")
+
+            if not isinstance(location_player, int) or not isinstance(location, int) \
+                    or (status_int is not None and not isinstance(status_int, int)):
                 await ctx.send_msgs(client,
                                     [{'cmd': 'InvalidPacket', "type": "arguments", "text": 'UpdateHint',
                                       "original_cmd": cmd}])
                 return
-            hint = ctx.get_hint(client.team, player, location)
-            if not hint:
-                return  # Ignored safely
-            if hint.receiving_player != client.slot:
-                await ctx.send_msgs(client,
-                                    [{'cmd': 'InvalidPacket', "type": "arguments", "text": 'UpdateHint: No Permission',
-                                      "original_cmd": cmd}])
-                return
-            new_hint = hint
-            if status is None:
-                return
+
+            hint = ctx.get_hint(client.team, location_player, location)
+
+            if status_int is None:
+                if hint is None:
+                    # New hints are created with unspecified by default
+                    status_int = HintStatus.HINT_UNSPECIFIED
+                else:
+                    # If the hint already exists and no status was provided, there is no point to the packet
+                    return
+
             try:
-                status = HintStatus(status)
+                status = HintStatus(status_int)
             except ValueError:
                 await ctx.send_msgs(client,
                                     [{'cmd': 'InvalidPacket', "type": "arguments",
                                       "text": 'UpdateHint: Invalid Status', "original_cmd": cmd}])
                 return
+
+            if hint is None:
+                if not create_if_not_exists:
+                    await ctx.send_msgs(client,
+                        [{
+                            "cmd": "InvalidPacket",
+                            "type": "arguments",
+                            "text": 'UpdateHint: Desired hint does not already exist. '
+                                    'Use with create_if_not_exists = True if the hint should be created.',
+                            "original_cmd": cmd
+                        }],
+                    )
+                    return
+
+                # UpdateHint can be used as an "Upsert", creating a new hint.
+                # The newly created hint must either be for a location in the requesting slot's world,
+                # or a location containing an item for the requesting slot (including item links).
+
+                target_item, item_player, flags = ctx.locations[location_player][location]
+
+                if client.slot not in ctx.slot_set(item_player):
+                    if status != HintStatus.HINT_UNSPECIFIED:
+                        await ctx.send_msgs(
+                            client,
+                            [{
+                                "cmd": "InvalidPacket",
+                                "type": "arguments",
+                                "text": 'UpdateHint: Must use "unspecified"/None status for items for other players.',
+                                "original_cmd": cmd
+                            }],
+                        )
+                        return
+
+                    if client.slot != location_player:
+                        await ctx.send_msgs(
+                            client,
+                            [{
+                                "cmd": "InvalidPacket",
+                                "type": "arguments",
+                                "text": "UpdateHint: No Permission",
+                                "original_cmd": cmd
+                            }],
+                        )
+                        return
+
+                new_hint = collect_hint_location_id(ctx, client.team, location_player, location, status)
+                ctx.notify_hints(client.team, new_hint)
+                ctx.save()
+                return
+
+            if hint.receiving_player != client.slot:
+                await ctx.send_msgs(client,
+                                    [{'cmd': 'InvalidPacket', "type": "arguments", "text": 'UpdateHint: No Permission',
+                                      "original_cmd": cmd}])
+                return
+            new_hint = hint
             new_hint = new_hint.re_prioritize(ctx, status)
             if hint == new_hint:
                 return

docs/network protocol.md

@@ -345,13 +345,15 @@ This is useful in cases where an item appears in the game world, such as 'ledge
 
 ### UpdateHint
 Sent to the server to update the status of a Hint. The client must be the 'receiving_player' of the Hint, or the update fails.
+Alternatively, if `create_if_not_exists` is set to true, the client can also be the 'finding_player' of the hint. In this case, the `status` must be `None` or 1 (unspecified).
 
 ### Arguments
 | Name | Type | Notes |
 | ---- | ---- | ----- |
 | player | int | The ID of the player whose location is being hinted for. |
 | location | int | The ID of the location to update the hint for. If no hint exists for this location, the packet is ignored. |
 | status | [HintStatus](#HintStatus) | Optional. If included, sets the status of the hint to this status. |
+| create_if_not_exists | bool | If true, a new hint will be created if the hint doesn't already exist. Defaults to false. |
 
 #### HintStatus
 An enumeration containing the possible hint states.