Usage of Gifting API

[Ziktofel]

What feature would you like to see?

https://discord.com/channels/731205301247803413/1101186175722598521/1304709275179945995

eudaimonistic — dnes v 8:28
A friend of mine who doesn't play Starcraft made a really interesting suggestion. What if SC2 took advantage of ⁠Gifting Specification / API in some way to share unit production? What if you could send units from one campaign to be controlled by another player in a different campaign?

I am nowhere near as versed in the current API, but the idea immediately sounded cool and the game already has the Nydus Worm as a conceptual bridge structure. Does this sound feasible?

https://discord.com/channels/731205301247803413/1134306496042258482

[Ziktofel]

Adding discussion from Discord

phaneros — dnes v 8:34
Sounds cool, and was suggested before many months ago. The big issue is our data bandwidth between client and game right now -- data is sent in with chat messages that can get throttled if messages are too frequent (can happen around a big release/collect that happens in-mission), and data is sent out by flipping bits on a secret structure, on which we have like ~15 bits per structure available or something like that (2 structures currently)
tl;dr not really feasible with our current infrastructure.

Sending data with bankfiles could make it possible, as that lets us send far larger amounts of data in xml format, with the format shared for both communication directions. But this would be a very large refactor and is out of scope for the current release most likely
Gameplay design-wise, I'd also worry it would just lead to degenerate gameplay of hoarding resources to send to another player, who can then send resources back once a new mission is started. So would take some workshopping or would end up being a less-used / meme option, which may reduce enthusiasm for a dev to pick it up as a project

Jamaican Castle — dnes v 9:18
It sounds like the "best" way to play would be to have one player play an easy mission that won't end on its own, and repeatedly farm it for resources to send to the others
which would be... not great

phaneros — dnes v 9:21
Yeah, that's what I'm worried about. On the one hand, you could say it's not the dev's role to tell the players they can't do that, which gets into the whole discussion about players optimizing the fun out of games. It might be too ungainly to use, it might be fun somehow, we don't know without testing. But the fact that it's a ton of effort with a significant risk it'll turn out that way means there's not going to be as much interest on the dev side. That is to say, I'd like to see the prerequisite refactor happen, but I'm not motivated to do the last bit aside for maybe a memey experiment

Salzkorn — dnes v 9:59
imo the problem with the abuse argument is that sc2 is not so extremely difficult as to really encourage people to use optimal strategies at all times
if someone wants to abuse gifting to beat a difficulty they couldn't beat otherwise, imo that's not a terrible thing
but yeah, it's absolutely the communication pipeline that's the main problem with gifting/energy link shenanigans/traps

Salzkorn — dnes v 10:08
re: bank files, I think the biggest issue with a file-based approach is that it creates an overhead period from the interval at which the file is read/written, which I imagine would make it less responsive for common communication like sending/receiving checks. I do think it's usable for less transient interactions like gifting or traps though

phaneros — dnes v 10:13
I don't think the communication speed would be much of an issue; checking the bank once per second seems reasonable, and I don't think people would mind a 1 second latency on receiving a check. The big bonus comes with throughput, though; we currently only have about 30 bits of data going from map to client, and using chat messages for client->map can crash the communication channel if too much goes in as sc2 will prevent a player from sending too many chat messages in a short period

Salzkorn — dnes v 10:16
nah, I'm not a fan of a 1s latency, I think there's a lot of joy in simultaneous finding & receiving between people
the throughput thing is only really an issue with big releases, which idk, I'm not convinced it's a massive problem
generally I feel "you sent so many items my game broke" is considered a positive sentiment among AP players, though I understand wanting to fix it anyway
overall I just don't think making the average experience worse for the sake of fixing an edge case is a great tradeoff

Bones — dnes v 10:33
Whenever I saw 'chat message ignored for too many messages' or whatever the error is, I would get worried that something is going to break and either I or the room admin will need to fix something, I can't say I ever felt joy about it. Obviously I understand now that is not the case now, but for a long time I worried about that.
I don't see how a 1 second delay between getting a check and getting the reward would even be noticeable. It's going to take about a second to even read what you got, so I don't see how it would degrade the experience. If we changed it and didn't say anything, I doubt anyone would even notice.
The chat message method has always felt weird since I've played the randomizer, and I assumed it was just necessary. Having a more legit method of transferring information between the client and game seems like a win on all fronts, except dev time of course.

Salzkorn — dnes v 10:39
it's not a 1 second delay between the check and reward though, it's 1 second minimum between the game and client

phaneros — dnes v 10:39
it's funny the first time, but it breaks all further communication so prevents you from getting further items for the rest of the mission. Which leaves a sour taste in my mouth more than a happy one

Salzkorn — dnes v 10:39
double that if you're playing by yourself or with other SC2s, and then add the actual server response time

phaneros — dnes v 10:40
I threw around 1s as a "I don't think anyone will care about this", we could go lower. It's a matter of what we set the checkup loop in the game trigger to be

Salzkorn — dnes v 10:40
there's absolutely a different social dynamic if you're in a call with someone, they talk about sending a cool item, and you're having to wait on it

phaneros — dnes v 10:41
I think 1 second is significantly less than the time it takes to say "I'm sending something cool"

Salzkorn — dnes v 10:43
I've already had experiences with sc2 where someone asked "is that good?" because our item names are ridiculous and I had to wait on the item to arrive
I really do think this would make it worse

phaneros — dnes v 10:43
Considering the number of deprecation warnings we get from the sc2 bot nowadays, I'm also uncomfortable with still staying locked to it as I don't think it'll work with future Python versions

Salzkorn — dnes v 10:43
err
that's not changing I think
lol
blizz would have to update the s2clientprotocol library

phaneros — dnes v 10:45
that's what I mean. When we run unit tests, we get several dozen "this is using a deprecated Python API, it will be removed in a future version" warnings, and they're all in the sc2 bot. So there's a chance the bot will just cease to function in a few Python versions
and it's unlikely Blizz would update the library to save us

Salzkorn — dnes v 10:45
iirc it's generated code bindings so nobody else can update it

phaneros — dnes v 10:45
so we'd just be screwed

Salzkorn — dnes v 10:45
yup
we can port the entire project to the arcade! =)
and then we'd have to use bankfiles, too

phaneros — dnes v 10:46
hence why I think it's good to at least explore in the direction of bank files. If 1s is a long delay for you, we could do 0.5s or 0.25s
The delay would come from how frequently the game/client check the bank

Salzkorn — dnes v 10:47
I'm also worried about sc2 potentially lagging at lower intervals, but that might be unfounded
but also again, I do think bank files have a potential use for us either way, there's no problem with experimenting for the main communication if we're building different communication anyway
Jamaican Castle — dnes v 10:47
does it actually have to release the file, close it, and reopen it every time?
the actual read should hardly take any time at all

phaneros — dnes v 10:48
I'd expect so, so the AP client has a chance to read/write it. Haven't experimented yet, though

phaneros — dnes v 10:49
not sure how far into the performance rabbit hole people here have explored; disk reads/writes are about the slowest order of magnitude operation you do on your own machine, but they're generally faster than network requests

Salzkorn — dnes v 10:49
I don't trust galaxy script enough to not expect some weirdness between opening a bank file and reading/parsing its contents
lord knows what funny data bindings go on in the background there

phaneros — dnes v 10:54
https://stackoverflow.com/a/53904470
Stack Overflow
How much faster is the memory usually than the disk?
IDE,SCSI,SSD,SATA or all of those.
Obrázek
So we'd be looking at minimum increased latency (vs nothing) of ~20ms
That's assuming a hard disk on 2012 hardware
Different topic, but I'm sad the message box is still draggable and stealing my inputs. Basically means I close the damn thing after the first time it bothers me, and I basically end up playing permanently without a message box, which is less exciting

[Salzkorn]

I've done some research and thinking for this.

Firstly, the gifting API has the drawback for us that we don't have a natural opportunity for users to type a recipient name, which is required. I think we can instead make a custom format, roughly based on Wonder Trade features from Pokemon AP implementations.

Secondly, I found it's possible to use the bot to vastly reduce the amount of necessary communication. The following is testing code for understanding the bot's capabilities, with the caveat that abilities currently don't work and require a (2 line) patch to the bot. I must've broken this when I cleaned up the bot a long time ago.

            for unit in self.all_own_units():
                if unit.name == GIFTING_NYDUS:
                    sc2_logger.info(f"Gifting Unit: {unit}")
                    # Check for orders (for buildings this is research or training)
                    if not unit.is_idle:
                        sc2_logger.info(f"  Order: {unit.orders[0].ability.link_name}") # button_name is probably more useful

                    # Check for passengers
                    passengers = unit.passengers
                    if len(passengers) > 0:
                        for passenger in passengers:
                            passenger_type = passenger._type_data
                            sc2_logger.info(f"  Passenger: {passenger.name} (Tag {passenger.tag}): Type {passenger_type.name}")

With GIFTING_NYDUS = AP_EngineeringBay and researching Terran Weapons level 1, I get this:

Gifting Unit: Unit(name='AP_EngineeringBay', tag=4296278017)
  Order: AP_EngineeringBayResearch

With GIFTING_NYDUS = AP_Bunker and loading 4 Marines, I get this:

Gifting Unit: Unit(name='AP_Bunker', tag=4358144001)
  Passenger: AP_Marine (Tag 4354473985): Type AP_Marine
  Passenger: AP_Marine (Tag 4300734465): Type AP_Marine
  Passenger: AP_Marine (Tag 4301520897): Type AP_Marine
  Passenger: AP_Marine (Tag 4357095425): Type AP_Marine

With these two in mind, I think the following design would work and is achievable:

1. Make a new building based on the Nydus Worm, with regular loading abilities and two new buttons for sending all units and getting a random unit.
   • I would propose a token cost on the "get" button too, to reduce abuse cases.
   • For code simplicity, there should be a cap of 1 for building these.
   • Loading abilities can take validators for units trying to enter the building, so special units (eg. timed-life units, Kerrigan, the Odin) can be banned, and in the worst case individual maps can override the validator to ban map-unique units.
2. The buttons start an extremely long research, which serves as a trigger for the AP client to interact with the AP server.
   • Additionally, the "send" button records its contents in SC2 triggers and then deletes the units. This should be safe if the above validators prevent all important units from being sent.
   • For code simplicity, the buttons might need to be disabled while the research is ongoing, but the research queue might solve this problem on its own?
3. The client uses AP's DataStorage API to handle commands as detailed below and then uses chat commands to report the result to SC2.
   • This falls under the previous bank file discussion, so feel free to consider the chat commands here a "for now" solution.
   • As far as I can tell, DataStorage is how Wonder Trade and the Gifting API both work under the hood. I saw Wonder Trade also has a system for handling simultaneous access which is probably yoinkable. The DataStorage would be named something like SC2_nydus_trade_{team}.

When the client gets a "send" command:

1. Record the unit types and amounts of units being sent (passengers of the Nydus).
2. Send a Set request to the DataStorage, with the above info as well as the local player.
3. On receiving a SetReply response, report the success to SC2 via chat message.
4. SC2 permanently deletes its local records of the sent units and cancels the Nydus' research.
5. If the server communication fails for any reason, the failure is reported to SC2 via chat message, and the original units are restored.

When the client gets a "get" command:

1. Send a Get request to the DataStorage.
2. On receiving a Retrieved response, build a list of available units, filtering out the units from the local player to avoid being able to send units to future missions.
3. Pick a random unit from the list.
4. Send a Set request to the DataStorage to notify the server of the picked unit.
5. Report the picked unit to SC2 via chat message.
6. SC2 spawns a new unit of the given type, puts it into the Nydus, and cancels the Nydus' research.
7. If the server communication fails for any reason, the failure is reported to SC2 via chat message, and SC2 refunds the cost of the "get" button.

If we run into message throughput issues from people spamming the buttons (though I suspect data communication will add a natural delay), just delaying the research cancel in SC2 (or adding a cooldown) would give enough downtime.