Add 'gotchas' to documentation

[BurnySc2]

Python-SC2 flaws:

• How to 'renew' Unit objects
• How to keep track of a Unit object over multiple frames
• Snapshots (once seen, not currently visible) have different tag than visible Unit
• Units that once went out of vision, morphed, and came back into vision, still have the same tags but different type_id (UnitTypeId)
• Some UnitTypeIds are confusing: Viking, VikingFighter, VikingAssault, LurkerDenMP, LurkerMP, LurkerBurrowedMP
• Distance calculation pdist and cdist: index X is out of bounds for axis 0 with size Y -> you are using Unit objects from an older game loop

SC2 API flaws:

• Can't unload single specific units from transports (bunker, medivac, prism, nydus, dropperlord)
• Cast range for creep tumors is 0 (while it is actually 10 if casted by non-queen)
• Workers are listed in self.state.dead_units when entering gas buildings and get called on unit finished when they leave the gas building
• Weapons (or weapon cooldown) is missing for some units, see https://github.com/BurnySc2/python-sc2/issues/7
• I put bot as player 1 and human as player 2, why doesn't it work? -> Have to put human as player 1
• Which unit is my cyclone locked on to? Or the other perspective: which cyclone is locked on to my unit? - Almost impossible to figure out

Good to know:

• Larva that gets issued, gets directly used
• Larva -> egg, keep the same unit tag. After the egg creates the drone or zerglings, the unit tag changes
• Unit tag changes when baneling hatches from banelingcocoon, but keep tag after morph to ravager and lurker https://discord.com/channels/350289306763657218/378866465807269888/973839186807382076

See also here: https://aiarena.net/wiki/bot-development/#wiki-toc-api-disparities

[ShadowLordAlpha]

Some notes about what is possible and what is not.

SC2 API flaws: 1) This is actually possible however you must have setRawAffectsSelection turned on as well as a few more details that I have not gotten to yet. However, MM and a few other bots now do this

2 & 4) This is true with actual SC2 maps but I believe we have been able to fix this in the new AIE map files that are now used on the ladder

Good to know: Here is a copy past from my tests that were performed as we were unsure what was actually happening ingame for a lot of this stuff

Ok, I just woke up and ran some tests and here is what happened.

1) Larva that is directly issued the morph command is the larve that is used. NOTE: i have never actually changed my larvae settings (select all larva is on) 2) The egg actually keeps the tag of the larva, its unit type does change though 3) the egg is destroyed when the unit it is morphing is finished and a new unit is created with a different tag

4) A drone is not marked as destroyed when it is turned into a building, however, it is no longer in the list. The building also has a new tag as well 5) when the building is canceled it is destroyed (duh) and the drone comes back but only with the idle call. The drone has its old tag which is different from the building

I think that was basically everything

[ShadowLordAlpha]

After more tests with the setting select all larva the larva is givin commands in order instead of the selected larva. for example, if you give 2 larva commands to morph into drones to larva 2 and 3 larva 1 and 2 will get those commands instead.

with that setting turned off it does select larva 2 and 3.

Do note that this is only testing early game with one base so it may not be exact for what happens with a lot of larva but it appears to select the drone in unit in pool order.

[mac2000]

Not sure if this is a right place to put it, but may be will help someone in future:

if you are on Windows and have installed StarCraft in an non defaul location, set SC2PATH environment variable before running examples script, e.g.:

SET SC2PATH=D:\Battlenet\StarCraft II
python examples\protoss\cannon_rush.py