Overview

Bot scripting in Dota is done via lua scripting. This is done at the server level, so there's no need to do things like examine screen pixels or simulate mouse clicks; instead scripts can query the game state and issue orders directly to units. Scripts have full have access to all the entity locations, cooldowns, mana values, etc that a player on that team would expect to. The API is restricted such that scripts can't cheat -- units in FoW can't be queried, commands can't be issued to units the script doesn't control, etc.

In addition to lua scripting, the underlying C++ bot code still exists, and scripts can decide how much or little of the underlying bot structure to use.

Bots are organized into three levels of evaluation and decisionmaking:
Team Level

This is code that determines how much the overall team wants to push each lane, defend each lane, farm each lane, or kill Roshan. These desires exist independent of the state of any of the bots. They are not authoritative; that is, they do not dictate any actions taken by any of the bots. They are instead just desires that the bots can use for decisionmaking.
Mode Level

Modes are the high-level desires that individual bots are constantly evaluating, with the highest-scoring mode being their currently active mode. Examples of modes are laning, trying to kill a unit, farming, retreating, and pushing a tower.
Action Level

Actions are the individual things that bots are actively doing on a moment-to-moment basis. These loosely correspond to mouse clicks or button presses -- things like moving to a location, or attacking a unit, or using an ability, or purchasing an item.

The overall flow is that the team level is providing top-level guidance on the current strategy of the team. Each bot is then evaluating their desire score for each of its modes, which are taking into account both the team-level desires as well as bot-level desires. The highest scoring mode becomes the active mode, which is solely responsible for issuing actions for the bot to perform.
Directory Structure

All in-development bot scripts live in the game/dota/scripts/vscripts/bots directory within your Dota 2 install. When you upload your bot script to the workshop, it will upload the contents of this directory. Downloaded scripts live in their own location within your Steam install.

The bot scripting API is structured such that there are multiple elements that can be independently implemented by bot scripts. What logic is overriden is determined by which functions you implement and the files in which they are implemented.

Each of the following scripting elements has its own script scope.
Complete takeover

If you'd like to completely take over control of a hero, you can implement a Think() function in a file called bot_generic.lua, which is called every frame in lieu of the normal bot thinking code. This will completely take over all bots -- no team-level or mode-level thinking will happen. You will be responsible for issuing all action-level commands to all bots. If you'd like to just take over a specific hero's bot, for example Lina, you can implement a Think() function in a file called bot_lina.lua.

Bots that have been completely taken over still respect the difficulty modifiers (see Appendix B), and still calculate their estimated damage.
Mode Override

If you'd like to work within the existing mode architecture but override the logic for mode desire and behavior, for example the Laning mode, you can implement the following functions in a mode_laning_generic.lua file:

    GetDesire() - Called every frame, and needs to return a floating-point value between 0 and 1 that indicates how much this mode wants to be the active mode.
    OnStart() - Called when a mode takes control as the active mode.
    OnEnd() - Called when a mode relinquishes control to another active mode.
    Think() - Called every frame while this is the active mode. Responsible for issuing actions for the bot to take.

You can additionally just override the mode logic for a specific hero, such as Lina, with a mode_laning_lina.lua file. Please see Appendix A for implementation details if you'd like to chain calls from a hero-specific mode override back to a generic mode override.

The list of valid bot modes to override are:

    laning
    attack
    roam
    retreat
    secret_shop
    side_shop
    rune
    push_tower_top
    push_tower_mid
    push_tower_bot
    defend_tower_top
    defend_tower_mid
    defend_tower_bottom
    assemble
    team_roam
    farm
    defend_ally
    evasive_maneuvers
    roshan
    item
    ward

Ability and Item usage

If you'd like to just override decisionmaking around ability and item usage, you can implement the following functions in an ability_item_usage_generic.lua file:

    ItemUsageThink() - Called every frame. Responsible for issuing item usage actions.
    AbilityUsageThink() - Called every frame. Responsible for issuing ability usage actions.
    CourierUsageThink() - Called every frame. Responsible for issuing commands to the courier.
    BuybackUsageThink() - Called every frame. Responsible for issuing a command to buyback.

If any of these functions are not implemented, it will fall back to the default C++ implementation.

You can additionally just override the ability/item usage logic for a single hero, such as Lina, with an ability_item_usage_lina.lua file. Please see Appendix A for implementation details if you'd like to chain calls from a hero-specific item/ability implementation back to a generic item/ability implementation.
Item Purchasing

If you'd like to just override decisionmaking around item purchasing, you can implement the following function in an item_purchase_generic.lua file:

    ItemPurchaseThink() - Called every frame. Responsible for purchasing items.

You can additionally just override the item purchasing logic for a single hero, such as Lina, with an item_purchase_lina.lua file.
Team Level Desires

If you'd like to supply team-level desires, you can implement the following functions in a team_desires.lua file:

    UpdatePushLaneDesires() - Called every frame. Returns floating point values between 0 and 1 that represent the desires for pushing the top, middle, and bottom lanes, respectively.
    UpdateDefendLaneDesires() - Called every frame. Returns floating point values between 0 and 1 that represent the desires for defending the top, middle, and bottom lanes, respectively.
    UpdateFarmLaneDesires() - Called every frame. Returns floating point values between 0 and 1 that represent the desires for farming the top, middle, and bottom lanes, respectively.
    UpdateRoamDesire() - Called every frame. Returns a floating point value between 0 and 1 and a unit handle that represents the desire for someone to roam and gank a specified target.
    UpdateRoshanDesire() - Called every frame. Returns a floating point value between 0 and 1 that represents the desire for the team to kill Roshan.

If any of these functions are not implemented, it will fall back to the default C++ implementation.
Hero Selection

If you'd like to handle hero picking and lane assignment, you can implement the following functions in a hero_selection.lua file:

    Think() - Called every frame. Responsible for selecting heroes for bots.
    UpdateLaneAssignments() - Called every frame prior to the game starting. Returns ten PlayerID-Lane pairs.

API Reference

There are two basic levels at which the API is available: globally, and on individual units. The following is a list of functions available at each level.
Global

(details WIP)

    GetBot
    GetTeam
    GetTeamMember

    DotaTime
    GameTime
    RealTime

    GetUnitToUnitDistance
    GetUnitToLocationDistance
    GetWorldBounds
    IsLocationPassable
    GetHeightLevel
    GetLocationAlongLane
    GetNeutralSpawners
    GetItemCost
    IsItemPurchasedFromSecretShop
    IsItemPurchasedFromSideShop
    GetItemStockCount

    GetPushLaneDesire
    GetDefendLaneDesire
    GetFarmLaneDesire
    GetRoamDesire
    GetRoamTarget
    GetRoshanDesire

    int GetGameState()
    Returns the current game state [LINK HERE]

    float GetGameStateTimeRemaining()
    Returns how much time is remaining in the curren game state, if applicable

    int GetGameMode()
    Returns the current game mode [LINK HERE]

    int GetHeroPickState()
    Returns the current hero pick state [LINK HERE]

    IsPlayerInHeroSelectionControl
    SelectHero
    GetSelectedHeroName

    IsInCMBanPhase
    IsInCMPickPhase
    GetCMPhaseTimeRemaining
    GetCMCaptain
    SetCMCaptain
    IsCMBannedHero
    IsCMPickedHero
    CMBanHero
    CMPickHero

    RandomInt
    RandomFloat
    RandomYawVector
    RollPercentage
    Min
    Max
    Clamp
    RemapVal
    RemapValClamped

    DebugDrawLine
    DebugDrawCircle
    DebugDrawText

Unit-Scoped

    Action_ClearActions
    Action_MoveToLocation
    Action_MoveToUnit
    Action_AttackUnit
    Action_AttackMove
    Action_UseAbility
    Action_UseAbilityOnEntity
    Action_UseAbilityOnLocation
    Action_UseAbilityOnTree
    Action_PickUpRune
    Action_PickUpItem
    Action_DropItem
    Action_PurchaseItem
    Action_SellItem
    Action_Buyback
    Action_LevelAbility

    GetDifficulty
    GetUnitName
    GetPlayer
    IsHero
    IsCreep
    IsTower
    IsBuilding
    IsFort
    IsIllusion

    CanBeSeen
    GetActiveMode
    GetActiveModeDesire
    GetHealth
    GetMaxHealth
    GetMana
    GetMaxMana
    IsAlive
    GetRespawnTime
    HasBuyback
    GetGold
    GetStashValue
    GetCourierValue
    GetLocation
    GetFacing
    GetGroundHeight
    GetAbilityByName
    GetItemInSlot
    IsChanneling
    IsUsingAbility
    GetVelocity
    GetAttackTarget
    GetLastSeenLocation
    GetTimeSinceLastSeen

    IsRooted
    IsDisarmed
    IsAttackImmune
    IsSilenced
    IsMuted
    IsStunned
    IsHexed
    IsInvulnerable
    IsMagicImmune
    IsNightmared
    IsBlockDisabled
    IsEvadeDisabled
    IsUnableToMiss
    IsSpeciallyDeniable
    IsDominated
    IsBlind
    HasScepter

    WasRecentlyDamagedByAnyHero
    WasRecentlyDamagedByHero
    TimeSinceDamagedByAnyHero
    TimeSinceDamagedByHero

    DistanceFromFountain
    DistanceFromSideShop
    DistanceFromSecretShop

    SetTarget
    GetTarget

    SetNextItemPurchaseValue
    GetNextItemPurchaseValue

    GetAssignedLane

    GetEstimatedDamageToTarget
    GetStunDuration
    GetSlowDuration
    HasBlink
    HasMinistunOnAttack
    HasSilence
    HasInvisibility
    UsingItemBreaksInvisibility

    GetNearbyHeroes
    GetNearbyTowers
    GetNearbyCreeps

    FindAoELocation

    GetExtrapolatedLocation
    GetMovementDirectionStability

    GetActualDamage

Editing in Progress