add market docs

docs/markets.md

@@ -0,0 +1,73 @@
+# Markets
+
+This document is an overview of how markets will work in the game. Not all of these details are currently implemented, but we wanted to share some of what SpaceTraders will offer when the game is released.
+
+Markets and trade are core concepts in the game and the primary credit-earning mechanism in SpaceTraders. Markets are dynamic and evolve over time as they are influenced by player activity. 
+
+- Prices will fluctuate with trade and the natural production / consumption of goods.
+- Trading drives the growth of a system, but a sudden drop in trade could also cause the system to fall into turmoil, instability and piracy.
+- Agents can earn credits from markets through arbitrage - connect a trade route between the export of one market to the import of another and collect the difference in trade price.
+- Markets evolve every day and agents who capitalize on these developing opportunities will be rewarded.
+- Early markets can be dominated by a single player, but several players will have to work together to grow and maintain more mature markets.
+- Agents can gain advanced notice of market events and shifts by leveraging their faction reputation or by spying on local comms.
+
+## Mechanics
+
+Markets have hidden mechanics that influence the price of goods, the trade volume of those goods, and market events that can occur with agent activity. Here is a quick overview of the basic mechanics of how markets function:
+
+- Markets are always in flux - prices are changing with the supply or consumption of goods. Sudden events can also disrupt or enhance trade.
+- Every trade good has a production rate (exports) and consumption rate (imports) which naturally drive price changes over time.
+- As agents purchase more and more of a exported trade good, the production of that good will increase until it catches up with demand
+- As agents supply more and more of an imported trade good, the consumption of that good will increase and may trigger new exports or settlement growth
+- A sudden drop in the trade of a good can quickly throw the market into instability - prices will hit extremes and eventually the settlement may fall into turmoil.
+- If you are investing long-term in a market or faction, you will want to trade consistently to keep prices stable.
+
+## Market Stages
+
+All markets can be categorized into three stages: early, developing, and mature. There will be higher profits in mature markets, but they will be difficult to find and maintain. The best way to trade in a mature market is to trade in an early or developing market until it evolves.
+
+### Early Markets
+
+Early stage markets trade in low volume and high price volatility but with better margins.
+
+- Early settlements often demand commodities such as food, clothing and medicine.
+- Supplying these settlements with their needs will provide high reputation rewards for early supporters, which can trigger the market to grow.
+- Early markets evolve into developing markets after a period of sustained trade and stability.
+
+### Developing Markets
+
+Middle stage markets rely on a steady supply of imports and regular transport of exports to continue to grow. Trade failures at this stage can quickly send the system into turmoil and piracy.
+
+- Settlements will eventually develop a primary export and may develop related imports
+- Developing markets will grow in trade volume and develop price stability with player activity
+- These markets are at the highest risk of collapse - a sudden drop in trade volume can throw the whole settlement into turmoil
+- Some markets will expand horizontally into related exports or develop brand new exports
+
+### Mature Markets
+
+Late stage markets export much rarer and higher-priced trade goods. These markets are often only accessible to agents with high reputation.
+
+- Export high-tech and luxury goods that are in high demand at most other settlements
+- Mature market goods are primarily sold through negotiation
+- Ships transporting high value goods will be likely targets for pirates and hostile factions
+
+### Black Markets
+
+Some goods will be prohibited by factions but can still be traded through negotiation. Although these trades can be lucrative, they can also destabilize the settlement and throw it into turmoil or piracy. Agents may want to prevent others from trading in black market goods by offering to patrol waypoints on behalf of the local faction.
+
+- Trading in black market goods can cause a significant drop in reputation if you're caught.
+- Ship modules such as hidden cargo holds, higher-tier envoys, and stealth tech can improve attempts at black market trade.
+- Ships can be scanned for black market goods which will be seized by patrols.
+- Agents can help factions patrol for black market cargo to prevent damage to the overall market by other agents or competing factions.
+
+## Exchanges
+
+Exchanges are markets with many types of goods listed and the prices remain fairly stable over time. These markets don't have a natural production or consumption rate, but slowly trend toward a medium price over time. Exchanges are a good way to exchange goods between agents or other ships.
+
+## Negotiation
+
+Not all opportunities are listed in the markets. Every settlement has the potential to buy or sell any trade good in the game. You can send an envoy to a settlement and attempt to negotiate the purchase or selling of a good - however the trade is not guaranteed. This can often be a more lucrative way of unloading cargo rather than jettisoning it into space.
+
+- Regular trade via these negotiations can sometimes trigger the development of a new import or export in the market.
+- High-tech and luxury goods are primarily sold through negotiation - these can net agents a great sum of credits.
+- Reputation with the local faction can have a significant impact on the types, prices and quantities of goods offered through negotiation.

models/MarketTrade.yaml

@@ -0,0 +1,18 @@
+description: ""
+type: object
+properties:
+  waypointSymbol:
+    type: string
+    minLength: 1
+  tradeSymbol:
+    type: string
+    minLength: 1
+  price:
+    type: number
+  tariff:
+    type: number
+required:
+  - waypointSymbol
+  - tradeSymbol
+  - price
+  - tariff