Skip to content

Commit

Permalink
docs: added tutorial 5 - terran gas. and refactored "base" to be "mai…
Browse files Browse the repository at this point in the history 
…n_base" everywhere.
  • Loading branch information
@dysonreturns
dysonreturns committed Mar 13, 2024
1 parent 873c180 commit 9fc8cab
Show file tree
Hide file tree
Showing 10 changed files with 378 additions and 94 deletions.
78 changes: 40 additions & 38 deletions docs/QUICK_REFERENCE.md
View file
Expand Up @@ -166,53 +166,55 @@ structures.not.creep_tumors.not.select_type(Api::UnitTypeId::SPINECRAWLER)
| all_units | full, unfiltered list of units+structures | F |
| effects | effects such as psi storm, lurker spikes | F |
| neutral.minerals | mineral patches | F |
| neutral.gas | gas geysers | F |
| neutral.geyser | gas geysers | F |
| neutral.watchtowers | Xel'Naga watchtowers | F |
| neutral.debris | destructible debris | F |

### Your Units and Structures

| method | type of Api::Unit's in UnitGroup | Fast/Med/Slow |
|------------------------------------------|------------------------------------------------------|---------------|
| structures | with attribute :Structure | F |
| structures.hq | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.townhalls | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.bases | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.creep_tumors | Zerg creep tumors (any) | F |
| structures.creep_tumors_burrowed | Zerg creep tumors burrowed underground | F |
| structures.pylons / structures.warpables | Protoss pylons | F |
| structures.warpgates | Protoss warp gates | F |
| structures.not.creep_tumors | all structures excluding creep tumors | F |
| units | not attribute :Structure | F |
| units.workers | SCV, Probe, Drone + Burrowed | F |
| units.larva | Zerg larva | F |
| units.queens | Zerg queen | F |
| units.overlords | Zerg overlords | F |
| units.army | units without: workers, queens, overlords, larva | F |
| units.warpables | Protoss warp prism | F |
| method | type of Api::Unit's in UnitGroup | Fast/Med/Slow |
|------------------------------------------|---------------------------------------------------|---------------|
| structures | with attribute :Structure | F |
| structures.hq | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.townhalls | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.bases | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| structures.gas | gas structures (Refinery, Assimulator, Extractor) | F |
| structures.creep_tumors | Zerg creep tumors (any) | F |
| structures.creep_tumors_burrowed | Zerg creep tumors burrowed underground | F |
| structures.pylons / structures.warpables | Protoss pylons | F |
| structures.warpgates | Protoss warp gates | F |
| structures.not.creep_tumors | all structures excluding creep tumors | F |
| units | not attribute :Structure | F |
| units.workers | SCV, Probe, Drone + Burrowed | F |
| units.larva | Zerg larva | F |
| units.queens | Zerg queen | F |
| units.overlords | Zerg overlords | F |
| units.army | units without: workers, queens, overlords, larva | F |
| units.warpables | Protoss warp prism | F |

### Enemy units
Same as Bot's `unit` and `structures` template, but prefixed with `enemy.`

| method | type of Api::Unit's in UnitGroup | Fast/Med/Slow |
|------------------------------------------------|--------------------------------------------------|---------------|
| enemy.all_units | enemy only, all units+structures | F |
| enemy.structures | with attribute :Structure | F |
| enemy.structures.hq | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.townhalls | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.bases | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.creep_tumors | Zerg creep tumors (any) | F |
| enemy.structures.creep_tumors_burrowed | Zerg creep tumors burrowed underground | F |
| enemy.structures.pylons / structures.warpables | Protoss pylons | F |
| enemy.structures.warpgates | Protoss warp gates | F |
| enemy.units | not attribute :Structure | F |
| enemy.units.workers | SCV, Probe, Drone + Burrowed | F |
| enemy.units.larva | Zerg larva | F |
| enemy.units.queens | Zerg queen | F |
| enemy.units.overlords | Zerg overlords | F |
| enemy.units.army | units without: workers, queens, overlords, larva | F |
| enemy.structures.not.creep_tumors | all structures excluding creep tumors | F |
| enemy.units.warpables | Protoss warp prism | F |
| method | type of Api::Unit's in UnitGroup | Fast/Med/Slow |
|------------------------------------------------|---------------------------------------------------|---------------|
| enemy.all_units | enemy only, all units+structures | F |
| enemy.structures | with attribute :Structure | F |
| enemy.structures.hq | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.townhalls | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.bases | Command Centres, PF, Nexus, Hatch, Lair, Hive | F |
| enemy.structures.gas | gas structures (Refinery, Assimulator, Extractor) | F |
| enemy.structures.creep_tumors | Zerg creep tumors (any) | F |
| enemy.structures.creep_tumors_burrowed | Zerg creep tumors burrowed underground | F |
| enemy.structures.pylons / structures.warpables | Protoss pylons | F |
| enemy.structures.warpgates | Protoss warp gates | F |
| enemy.units | not attribute :Structure | F |
| enemy.units.workers | SCV, Probe, Drone + Burrowed | F |
| enemy.units.larva | Zerg larva | F |
| enemy.units.queens | Zerg queen | F |
| enemy.units.overlords | Zerg overlords | F |
| enemy.units.army | units without: workers, queens, overlords, larva | F |
| enemy.structures.not.creep_tumors | all structures excluding creep tumors | F |
| enemy.units.warpables | Protoss warp prism | F |

### Unit Group filters

Expand Down
28 changes: 14 additions & 14 deletions docs/TUTORIAL_02.md
View file
Expand Up @@ -13,8 +13,8 @@ For Terran, you train a worker from the building you see on screen, the Command

```ruby
def on_step
base = structures.hq.first
base.build(unit_type_id: Api::UnitTypeId::SCV)
main_base = structures.hq.first
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
end
```

Expand All @@ -24,17 +24,17 @@ Aliases include `structures.bases` and `structures.townhalls`, but we prefer `hq
Since we only have one at the start, `structures.hq.first` selects our main base's Command Centre and assign to to a local variable `base`.
On this base, we call the `build` action.
```ruby
base.build(unit_type_id: Api::UnitTypeId::SCV)
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
```
`build` has an alias of `train`, if `base.train(unit_type_id: Api::UnitTypeId::SCV)` reads better for you.
`build` has an alias of `train`, if `main_base.train(unit_type_id: Api::UnitTypeId::SCV)` reads better for you.

Unit actions are all actually some form of an Ability being triggered on a Unit, such as MOVE, STOP, ATTACK.
When calling `build` the library translates the Unit Type Id of SCV into the correct Ability Id for you and calls an action in the background.

These two commands do the same thing:
```ruby
base.build(unit_type_id: Api::UnitTypeId::SCV)
base.action(ability_id: Api::AbilityId::COMMANDCENTERTRAIN_SCV)
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
main_base.action(ability_id: Api::AbilityId::COMMANDCENTERTRAIN_SCV)
```

It's recommend to call `action` when performing abilities and `build`/`train` when creating Units, for your own clarity.
Expand Down Expand Up @@ -63,10 +63,10 @@ def on_step
# How many units do we have supply or "food" for.
supply_available = common.food_cap - common.food_used

base = structures.hq.first
main_base = structures.hq.first
# Ensure we have enough minerals and enough space for this unit
if common.minerals > 50 && supply_available > 0
base.build(unit_type_id: Api::UnitTypeId::SCV)
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
end

end
Expand Down Expand Up @@ -127,7 +127,7 @@ We therefore internally track all you spending of minerals/vespene/supply and yo
puts common.minerals #=> 100
can_afford?(unit_type_id: Api::UnitTypeId::SUPPLYDEPOT) #=> true. depots cost 100.

base.build(unit_type_id: Api::UnitTypeId::SCV) # Costs 50. 100 - 50 = 50 remaining
main_base.build(unit_type_id: Api::UnitTypeId::SCV) # Costs 50. 100 - 50 = 50 remaining
puts common.minerals #=> still 100
puts @spent_minerals #=> 50

Expand Down Expand Up @@ -157,17 +157,17 @@ Let's simplify the previous example with `can_afford?` and also limit the build

```ruby
def on_step
base = structures.hq.first
main_base = structures.hq.first

if can_afford?(unit_type_id: Api::UnitTypeId::SCV)

workers_in_progress = base.orders.size
workers_in_progress = main_base.orders.size
if workers_in_progress == 0
# Scenario 1: Queue is empty, lets build
base.build(unit_type_id: Api::UnitTypeId::SCV)
elsif workers_in_progress == 1 && base.orders.first.progress < 0.9
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
elsif workers_in_progress == 1 && main_base.orders.first.progress < 0.9
# Scenario 2: Queue has one unit, which is almost completed (== 1.0), so let's start another
base.build(unit_type_id: Api::UnitTypeId::SCV)
main_base.build(unit_type_id: Api::UnitTypeId::SCV)
else
# no operation. don't over-queue.
end
Expand Down
8 changes: 4 additions & 4 deletions docs/TUTORIAL_03.md
View file
@@ -1,7 +1,7 @@
# TUTORIAL 3

# Terran
## Structures
## Structures and placement

Moving ahead without Terran build, it's time to add structures.
We already know that we wish to build a supply depot (`Api::UnitTypeId::SUPPLYDEPOT`), but where do we want to build it?
Expand All @@ -25,7 +25,7 @@ We will work in blocks of 3x3 even though the supply depot size is 2x2, to allow

```ruby
# Print label for Command Centre position
debug_text_world("^ [#{base.pos.x}, #{base.pos.y}]", point: base.pos)
debug_text_world("^ [#{main_base.pos.x}, #{main_base.pos.y}]", point: main_base.pos)

# Debug all the points for length 3x3 which are buildable
geo.build_coordinates(length: 3).each do |x, y|
Expand Down Expand Up @@ -70,7 +70,7 @@ def on_step
builder = units.workers.random

# Get location near base 3-spaced for out 2x2 structure to prevent blocking ourselves in.
build_location = geo.build_placement_near(length: 3, target: base)
build_location = geo.build_placement_near(length: 3, target: main_base)

# Tell worker to build at location
builder.build(unit_type_id: Api::UnitTypeId::SUPPLYDEPOT, target: build_location)
Expand All @@ -91,7 +91,7 @@ You might not be able to immediately resolve the issue, but we can be a bit more
By default, `build_placement_near` returns the point nearest to the requested `target:`, but `build_placement_near` also has an optional `random:` parameter.
What this `random:` does, is fetch the nearest N placements and then randomly selects one of them.
```ruby
build_location = geo.build_placement_near(length: 3, target: base, random: 3)
build_location = geo.build_placement_near(length: 3, target: main_base, random: 3)
```
The above example chooses a build location from the 3 nearest suitable placement blocks near your main base.
If one of them is blocked, you can potentially unblock yourself on the next attempt.
Expand Down
10 changes: 5 additions & 5 deletions docs/TUTORIAL_04.md
View file
Expand Up @@ -80,10 +80,10 @@ Finally, lets review the action we added.
builder.smart(target: nearest_mineral, queue_command: true)
```

We've used a new action method on a Unit, called `smart`, which is what the client calls a right-click.
`Api::AbilityId::SMART` does different actions depending on what happens in-game when you right-click. For army units, it might issue an attack command.
We've used a new action method on a Unit, called `smart`, which is what the client calls a Right-Click.
`Api::AbilityId::SMART` does different actions depending on what happens in-game when you Right-Click. For army units, it might issue an attack command.

Below is a list of **common action methods**, which work for bot a Unit and UnitGroup. You'll recognize `build` and `train`.
Below is a list of **common action methods**, which work for both a Unit and UnitGroup. You'll recognize `build` and `train`.

- `action` - a raw action. every other method pipes through this.
- `build` / `train`
Expand All @@ -106,8 +106,8 @@ You can see it in action if you followed along or by checking out [04_terran_com

---

Those lost workers are now happily back in the production line and not a mineral wasted.
But you can't build machines if you don't have the green. Let's gather some vespene gas.
Those lost workers are now happily back in the production line and not a mineral wasted.
But minerals are not everything, let's harvest some vespene gas.

---

Expand Down

0 comments on commit 9fc8cab

Please sign in to comment.