Skip to content

Latest commit

 

History

History
166 lines (111 loc) · 8.97 KB

Market 536f0cd46bb945da812d4b8ee57c4355.md

File metadata and controls

166 lines (111 loc) · 8.97 KB
Raw

Market

One of the special features of this game is that players are allowed to upgrade their tank; this page is a description of the upgrading mechanism.

Upgradable items

  • max HP
  • weapons
  • visible range
  • size (area) of tank body
  • the shape of the tank body (users could change the number of edges of polygons, notice that the area of the tank body will not be changing)
  • moving speed of tanks
  • API call token per second

specifically for weapons, these features are upgradable:

  • maximum bullet capacity
  • launching rate
  • refill rate (time taken to fill up available bullets to their maximum capacity)
  • number of barrels
  • damage per bullet
  • flying speed of bullets
  • width of bullet

Pricing Mechanisms

There are some possible pricing mechanisms:

  1. none: No rule.
  2. auction: for every fixed time interval, the system will randomly select an upgradable item. The system will accept bids for a fixed time interval (e.g., 10s since we need to consider human players), and the player with the highest bid will gain the upgrade. During the auction process, the bid history and the current maximum bid should be available to all players.
  3. auction with user-selected items: The main disadvantage of the direct auction is that users cannot upgrade their needed items if they are randomly selected by the system. One improvement is to circulate the ability to start auctions to different users. That is: for a fixed time interval, a user will be selected to choose an item on auction. Notice that, the user will only have the power to start the auction, not directly owning the item. This improvement will increase the chance for players to get their wanted upgrades.
  4. a combination of 2 and 3.
  5. frequency: All upgrades will be assigned a fixed price; in the game, the price will change in real-time according to the frequency of purchase and sell (players can both purchase and sell upgrades in this game). Each time a player purchases an upgrade, the price of this upgrade increases by a fixed number, and each time a player sells, the price decreases by the number.
  6. place: different areas on the map may have different prices for upgrades. Players can buy or sell upgrades at the local price. Buying will increase the price and selling will decrease the price of a place, so players can only make limited money by selling between places. // IS THIS NEEDED?

Controller APIs

Every controller has a read-only field called the market. Every action involving action with the market is under the market object. For example, in the standard auction rule,

controller.getMarket().bid(200);

or in Kotlin:

 controller.market.bid(200);

means to offer a bid of 200 money.

All market object implements Market interface, which contains one getName() function to specify the name of the pricing rule. It also contains a queue of things waiting to be upgraded (to be processed by the game core). The APIs provided by different pricing rules may vary. And in the following part, the API of each pricing rule will be introduced.

Auction

serial name: auction.

val upgradableItemsInfo

or getUpgradableItemsInfo() for java. (for other APIs, the same pattern holds, and this line will not be further repeated)

  • accept no parameters
  • returns a List of upgradeEntry<out Number>, which contains the following entries:
    • type: enum type of upgradeType indicates after receiving this upgrade, what field will be changed.
    • incrementMax / incrementMin : indicate the range of value of the upgradable item in increment mode (such as increase HP). If in auctions, the item will not be available in increment mode, then these two values should be all set to zero.
    • valMax / valMin : indicate the range of value of upgradable item in value mode. set to zero when not available.
    • possibility : Double : the possibility (or ratio) of selecting this item in the next auction.

val nextAuctionTime

  • accept no parameters
  • return in Long, indicate the time to start the next auction, and notice that this time is game time (time elapsed after the game starts). If there is an ongoing auction, this function will return the auction start time after this one.

val auctionEndTime

  • accept no parameters
  • return in Long , indicate when will the current auction end (in terms of game time). If inAuction returns false, then this value will be -1.

val inAuction

  • accept no parameters
  • return in Boolean , indicate whether there currently is an ongoing auction.

val inAuctionBlock

  • accept no parameters
  • return in Future<Boolean> , when calling inAuctionBlock.get() , true will always be returned. Using this function, the player can block their code until the start of the next auction.

val curAuctionItem

  • accept no parameters
  • return an UpgradeRecord to inform the item being auctioned

val bidHistory

  • accept no parameters
  • returns a List of BidRecord sorted by time (index 0 is the most recent bid), which contains the following fields:
    • uid : Long : the uid of the player that made the bid
    • price : Int : the price of this bid
    • timeStamp : Long : the game time when making the bid

val minBidInterval

  • accept no parameters
  • returns in Long means the minimum time interval between two bids. The unit is milliseconds.

val curWinningBid

  • accept no parameters
  • returns in bidRecord indicate the winning bid if no further bid is made.

bid(price : Int)->Boolean

  • use this function to make a bid in the auction
  • return false if the bid failed, true otherwise. In the following cases, this function will return false:
    • When your price is lower or equal to the current max bid made by others
    • When you made too many bids in a given time, this limitation is added so that the server will not be blocked by too many requests. This limitation could be obtained by minBidInterval

onAuctionStart(callBack : ()->Unit)->Boolean

  • the function receives a user-defined function as a parameter. callBack should be a function with no parameter nor return values.
  • Once an auction is started, callBack will be called in a new thread. If multiple users define their callBack, the order of starting these callBack will be randomly generated in each auction.
  • Each user can start a limited amount of threads (which can be found in APIs in controller), and calling this specific function will start a new thread whenever there is an auction. If the user has already started too many threads (for example, the previous callback never returns), this function will return false.

Communication

GUI to Server

When GUI sends a request related to the game server, bid, for example, the format should be as follows:

1234 market.bid 200

the market prefix indicates that this request is related to the market.

Event Format (Server to GUI)

The format of the “Market Change Event” depends on the pricing rule. The following paragraphs show all the fields of “market change event” under each pricing rule. Notice that this information is encoded in JSON format and should be sent from the server to the GUI (also stored to local files when replay-saving functionality is on)

Auction

The format is either one of the following:

  1. If it is the beginning of an auction, the event should include:
    • toSell: an array indicating the item to be sold. For example: ["HP", true, 10] The first element (string) indicates the field to be changed after purchasing the item, and the second element (boolean) indicates whether the next number is an increment or the value after purchase. For example, if the current HP of a player is 114, then after purchasing the previous upgrading item, the HP of the user will become 114+10=124. If the second element is changed to false, then in the same scenario, the HP will become 10.
    • minBid: number (optional). The minimum bid a player should offer.
    • endT: the game time at which this auction ends.
  2. If it is in the middle of an auction, the event should include:
    • bidder: integer. The tank element UID of the player offering a bid.
    • price: number. The price offered by the bidder.
    • Events during the auction to reveal prices are optional.
  3. If it is the end of an auction, the event should include:
    • buyer: integer, optional. The tank element UID of the player who buys it. If not set or equals null, then it means that no one participated in the auction.
    • price: number. The final price of the bidder.
    • nextT: The start time (game time) for the next bid begins. If undefined, the next auction will start until the client receives the next “auction start” event, but the GUI will not display the time to indicate when the next auction starts.

Note that despite the format of the “market update event” being different in the different stages of the auction, all of them have the same serial name - MktUpd. The client should distinguish them by their unique fields.

Frequency

TODO

Place

TODO