Trader API (progress report and planning)

[robject]

Okay, I bought the domain rhylanor.space for one year for 99 cents. I already own hardware for hosting, so I didn't rent that... I'll just forward to the target application's port on my hosting machine.

Now I have a landing domain for my trading game. And as part of work training, I am designing a RESTful interface to my trading game. So by the end of the year I can have it stood up.

It's a bare-bones trading program. You jump from system to system on a ship with a crew, trading as you go and picking up (and dropping off) passengers (automatically). Travellermap is the "navigational database", which means you can travel absolutely anywhere in Charted Space.

The trade/passenger engine works correctly, though it is automatic. Players are unique, so multiple players are supported. Characters have skills, currently only utilized for finding passengers and freight. Ships have the usual characteristics, although only jump and payload spaces are currently used. Worlds, which come from Travellermap, have the full UWP, though again only some of it is used.

But that's all it is. The main goal is to put in the REST API so that players can interact with it.

 

[BRJN]

Sounds interesting!
- Will the different Milieus be available through future expansions?
- Does the game use standard ships, or is there a way to enter "special modifications"?

 

[robject]

Sounds interesting!
- Will the different Milieus be available through future expansions?
- Does the game use standard ships, or is there a way to enter "special modifications"?

Part of my long list of things I'd like to see includes custom ships. I can see a "linter" that imports a ship file in JSON format from my Desktop Shipyard (or any compatible program).

I see no problem changing the milieu data used, as long as Travellermap has it. I'd want to do that anyway so that I can examine the M1900 starchart from an experiential angle, so to speak.

 

[robject]

For Phase 1, I want to support:

POST /player ; create a player
GET /player/$id ; get a full player record by ID (includes location and ship data)
PUT /player/$id ; update player record

GET /player/$id/world ; get player's location record
PUT /player/$id/world ; jump to a mainworld

GET /player/$id/cargo ; get player's cargo manifest
PUT /player/$id/cargo ; execute buys and sells

GET /player/$id/passengers ; get player's pax manifest
PUT /player/$id/passengers ; unload and load pax

 

[McPerth]

May I suggest you to look at this thread for a symilar game where you can take ideas from, and even trying to contact its creator (though he hasn't logged in for a while now)?

 

[robject]

Thanks for that McPerth. Alas I don't have Windows at home; i will try to find a bit of time to try it at work.

 

[Matt123]

I started down this route, also using the Traveller Map API. Mostly to take the next step on my TCS app. I got as far as being able to navigate a fleet (my abstraction, a fleet is easily one vessel) around the map.

If you email me direct I'm happy to share server code (written in Ruby) that works out jump distances and other stuff as well as a link to a prototype web interface. You will want to improve on the interface as it was mostly developed so I could test code, but it might be a useful starting point. At the time I stopped I was exploring using a gif to represent the fleet or ships location on the map.

My email address is on my TCS apps web site. (my COTI mailbox is full).

In any case, have fun

Cheers

 

[robject]

Currently implemented:

POST /player ; create a player
GET /player/$id ; get a full player record by ID (includes location and ship data)

GET /player/$id/world ; get player's location record
PUT /player/$id/world ; jump to a mainworld

GET /player/$id/hex ; get player's sector-hex location (only)

GET /player/$id/ship ; get player's ship record


So a player can jump from world to world in a Beowulf (but not into an empty hex).

 

[McPerth]

What trade system do you intend to use?

 

[robject]

What trade system do you intend to use?

I implemented the T5 trade system (which itself is a descendant of Merchant Prince). I have yet to wire it into the SpringBoot REST framework I've been adding in this week.

 

[McPerth]

I implemented the T5 trade system (which itself is a descendant of Merchant Prince). I have yet to wire it into the SpringBoot REST framework I've been adding in this week.

The game in the thread I told you can use MT or MgT systems. I'm afraid I've already given too many times my opinióo about MP system (and its descendants).

Another point, you say the for now your program only uses skills to find cargoes and passengers. IMHO their main use is steward (to care for passengers, as it limits them) and bróker (to have better prices). At lest in most Traveller editions, I cannot say about T5...

 

[whartung]

For Phase 1, I want to support:
GET /player/$id/world ; get player's location record
PUT /player/$id/world ; jump to a mainworld

Does this "do anything"? i.e. are there any side effects of this? (Time passes, fuel is consumed, etc.)

Are "player" and "ship" synonymous? (i.e. shouldn't the ship jump, and the player(s) move along with it?)

Perhaps POSTing an itinerary will update that the ship moved (and didn't misjump! yay for maintenance!), the players moves, the fuel gets burned, and the clock tics by.

GET /player/$id/cargo ; get player's cargo manifest
PUT /player/$id/cargo ; execute buys and sells

Similarly here, not to get all dogmatic, but its better to POST a sales transaction that then effects other resources (notably inventory, cash on hand, and the ledger) than PUTting to the cargo and performing a differential analysis to suss out "what happened".

The GET should represent your current cargo, a PUT would change that cargo (since it's ostensibly the same resource, and representation), but that may not be the place to capture things like cargo values and such.

You HAVE 10 tons of bicycle parts. The Ledger tracks how much the parts are worth. The Ledger tracks whether you bought 1 lot of 10tons for 100 credits, vs two lots of 5 tons each, one for 25 credits (what a deal!) and the other for 75 (not so much of a deal).

So, POSTing a sales transaction captures that information (Sold 2 tons of bicycle parts on Regina @ 15cr per ton, paid 10% commission to the broker.) As the transaction processes, your cash on hand, your ledger, and your cargo are all summarily updated.

GET /player/$id/passengers ; get player's pax manifest
PUT /player/$id/passengers ; unload and load pax

Similar discussion here.

 

[robject]

Hey, you're right about POSTing cargo and passengers. Thanks.

Player and Ship are separate critters. A Player has a location, and could have a Ship [that he is on by definition]. "Has" doesn't mean "ownership", it means "commands". The relationship is strong.

And I don't yet let players POST "themselves" as passengers. I'll think about THAT.

For the trade engine, since it's decoupled from the rest of the logic, I'm going to install it in a separate service (can you say "micro"?).

 

[robject]

Now on GitHub. Early days, mind you.

https://github.com/bobbyjim/tradersb

 

[robject]

The API now supports changing ships and customization. There is minimal validation, so abuse is easy. 20 basic ship types are coded in, more or less approximately correct (I went off of my memory):

Beowulf A-BS11
Marava  A2-BS12
Cruiser C-HU33
Leviathan CM-RC43 
Gazelle E-DS53    
Frieghter F-KS13  
Frigate G-FS52    
Seeker J-AA11     
Safari K-BA12     
Lab L-DC12        
Liner M-FS13       
Long-Liner M2-ZS14 
Corsair P-DS42
Merchant R-DS11
Scout S-AA22 
Transport T-KU12
Packet U-CA33
Barge W-AC11 
Xboat X-AC04 
Yacht Y-EL41

I've also added endpoints for getting your skills list and adding/improving skills.

The back-end service can build Cargos and Trades based on T5 rules. Once this is wired to the API, you can then start making money. I am considering these endpoints:

GET /players/$id/cargo           see cargo available on this world
POST /players/$id/cargo          buy and load cargo
DELETE /players/$id/cargo/$cid   sell cargo on current world

POST /players/$id/freight        load freight 
DELETE /players/$id/freight      unload freight

GET /players/$id/passengers      see H/M/L passengers available
POST /players/$id/passengers     take on passengers
DELETE /players/$id/passengers   deplane passengers

 

[robject]

I'm not sure how best to write the API for actual trading!


In order to *find* cargo, you just need the source world.

In order to *find* freight, you need the source world, the ship's demand, and any applicable skill DM.

In order to *find* passengers, you need the source world, the ship's passage demand, and the skill DM applicable to the passage type (high, medium, low).

 

[aramis]

Why not just use one data structure, and then act only upon the relevant subcomponents? It simplifies the dataspace...

 

[Matt123]

Just adding to Aramis's observation, Ships, Star/Space ports and Corporate offices all share common traits. For example;

location, including sub-location, eg: Main-surface, Main-orbit, GG1-orbit, GG1-Moon1
ownership, PC, NPC, corporate or government
manifest, including general cargo, 'named' cargo and passengers
trading skills, an average perhaps of 2 or specific skills owned by the player or NPC
cash/credit available
profit % desired, based on anticipated purchase or sales price. The algorithm using this could be quite fun to develop
movement, J0 in most cases, J1-6 for ships

Just random thoughts to use or discard.

 

[whartung]

I'm not sure how best to write the API for actual trading!


In order to *find* cargo, you just need the source world.

In order to *find* freight, you need the source world, the ship's demand, and any applicable skill DM.

In order to *find* passengers, you need the source world, the ship's passage demand, and the skill DM applicable to the passage type (high, medium, low).

You first need the concept of "time". Since, everything has a time component, not just the others.

For example, if you GET /world/rhylanor/available_cargo, you could get a list of current, available cargoes. That list will remain static until you POST /purchase/rhylanor a purchase order for some new cargo, OR until "POST /nextday{week/trip}" or whatever. Or until you leave the system (for a single player game).

Once the clock moves ahead, then all of those things reset.

In a single player instance, you can simply use Jump as your clock. Also, with a single player instance, you can have the player "log in", and thus establish a global context that overlays all of the other transactions (such as DMs for the player/crew/ship).

There's nothing stopping you from doing something like putting the Ship credentials as part of the Authorization header. For example, you can just GET /world/rhylanor/available_cargo without an the header, and you get a general list of stuff available to "everyone". Add an Authorization header, so now we know who you represent, then you may see other cargos, or "prices just for you".

Using the larger context lets you do things like GET cargos from other worlds, with the caveat that you'll only get what you last saw when you were there, unless you have some kind of trading forum where traders share what they saw when they were there last. But even then, that's going to be out of date by the number of jumps between where you are, and where the system is.

You just need to establish what kind of identity you want to assert. To me, the "ship" along with it's crew is the natural choice, rather than just a character. But it's all relative.

As a Game Player, the Ship seems the natural artifact of control.

So, "log in" to the system with "your ship credentials". The system knows where the ship is, know what the state of the universe is (and was). If you're at Rhylanor, and want the cargos for Regina, you can simply refuse to offer anything "because you're not there". Nothing wrong with that, keep it simple. If the player wants to know what was there before, they can keep notes.

But fundamentally, you need an entity of context to affect the transactions, and you need time to move things like availability along.

 

[Maksim-Smelchak]

Okay, I bought the domain rhylanor.space for one year for 99 cents. I already own hardware for hosting, so I didn't rent that... I'll just forward to the target application's port on my hosting machine.

Now I have a landing domain for my trading game. And as part of work training, I am designing a RESTful interface to my trading game. So by the end of the year I can have it stood up.

It's a bare-bones trading program. You jump from system to system on a ship with a crew, trading as you go and picking up (and dropping off) passengers (automatically). Travellermap is the "navigational database", which means you can travel absolutely anywhere in Charted Space.

The trade/passenger engine works correctly, though it is automatic. Players are unique, so multiple players are supported. Characters have skills, currently only utilized for finding passengers and freight. Ships have the usual characteristics, although only jump and payload spaces are currently used. Worlds, which come from Travellermap, have the full UWP, though again only some of it is used.

But that's all it is. The main goal is to put in the REST API so that players can interact with it.

Mazel Tov, Rob!

Shalom,
Maksim-Smelchak.