@thetinyspark/paradox v1.8.0
Description
A typescript engine for 'management games' like 'Age of Empires'.
How to install ?
npm install @thetinyspark/paradox
Getting started
The engine provides some usefull methods to interact with. First, you need to init the Engine with a configuration:
import * as Paradox from "@thetinyspark/paradox";
const templateBuildings = [
{
id: 1, // building's template uid
name: "Castle", // building's name
levels: [ // all possible levels for this building
{
level: 1,
cost: [{resourceID: 1, amount: 100}], // amount of resources needed to buy this building's level
prod: [{resourceID: 2, amount: 100}], // amount of resources produced each cycle by the building at this level
cons:[{resourceID: 2, amount: 2}], // amount of resources consumed each cycle by the building at this level
sold:[{resourceID: 1, amount: 50}] // amount of resources gained when this building is sold at this level
},
{
level: 2,
cost: [{resourceID: 1, amount: 200}],
prod: [{resourceID: 2, amount: 200}],
cons:[{resourceID: 2, amount: 3}],
sold:[{resourceID: 1, amount: 100}]
},
]
},
{
id: 2,
name: "Home",
levels: []
},
];
const resources = [
{
id:1, // resource's uid
name: "gold" // resource's name
},
{id:2, name: "wood"},
{id:3, name: "food"}
];
const configuration = {
cities: [], // starts with no predefined cities
resources, // exhaustive list of resources used the game
templateBuildings // templates which are used to build all the buildings
};
Paradox.engine.init(Paradox.defaultContainer, configuration);
Data Types used to import / export data to/from the engine
// The 'configuration' sent to 'Paradox.engine.init(Paradox.defaultContainer, configuration)' must match this type
type GameSaveDescType = {
cities?: CityDescType[],
resources?: ResourceDescType[],
templateBuildings?: TemplateBuildingDescType[]
};
// Others data description types
type ResourceDescType = {
id:number,
name:string
};
type QuantityDescType = {
resourceID:number,
amount:number
};
type BuildingLevelDescType = {
level: number,
cost: QuantityDescType[],
prod: QuantityDescType[],
cons: QuantityDescType[],
sold: QuantityDescType[]
};
type TemplateBuildingDescType = {
id: number,
name: string,
levels: BuildingLevelDescType[]
};
type CityBuildingDescType = {
tplID:number,
level:number
};
type CityDescType = {
id: number,
name: string,
buildings:CityBuildingDescType[],
wallet: QuantityDescType[]
}
type CityPointerType = {
id: number
}
type CreateCityBuildingType = {
cityID: number,
tplID:number
};
type CityBuildingPointerType = {
cityID: number,
id:number
};
type SetBuildingFrozenStatusType = {
cityID: number,
id:number,
frozen:boolean
};
The Engine object and its methods
The Engine
object, available from the Paradox.engine
property, provides
a lot of usefull methods to interact with its core. Here are some basic use cases which
used those methods.
Cities
Add a city
const cityData:CityDescType = {
id: 1,
name: "Atlantis",
buildings:[{tplID:1, level:2}],
wallet: [{resourceID: 1, amount: 100}]
};
Paradox.engine.addCity(cityData);
Remove a city
const data:CityPointerType = {id:1};
Paradox.engine.removeCity(data);
Get all cities
Paradox.engine.getCities().then(
(cities:City[]) => {
// ...
}
);
Get a city by its id
Paradox.engine.getCityByID({id:1}).then(
(city:City) => {
// ...
}
);
Create multiples cities at once
const cities:CityDescType[] = [
{
id: 1,
name: "city1",
buildings:[],
wallet:[{resourceID: 1, amount: 100}, {resourceID: 2, amount: 100}]
},
{
id: 2,
name: "city2",
buildings:[],
wallet:[{resourceID: 1, amount: 50}, {resourceID: 2, amount: 50}]
},
];
Paradox.engine.createCities(cities);
Resources
Create multiple resources at once
const resources:ResourceDescType[] = [{id:1, name: "gold"},{id:2, name: "wood"},{id:3, name: "food"}];
Paradox.engine.createResources(resources)
Get all resources
Paradox.engine.getResources().then( (resources:Resource:[])=>{});
Buildings
Adds a building for free to a city
const data:CreateCityBuildingType = {cityID: 1, tplID: 1};
Paradox.engine.addBuilding(data);
Freezes a city's building
A frozen building cannot consume nor produce anything on cycle
const data:SetBuildingFrozenStatusType = {cityID: 1, id: 1, frozen:true};
Paradox.engine.setBuildingFrozenStatus(data);
Buys a building and add it to a city (if city has enough resources)
const data:CreateCityBuildingType = {cityID: 1, tplID: 1};
Paradox.engine.buyBuilding(data);
Upgrades a building level (if city has enough resources)
const data:CityBuildingPointerType = {cityID: 1, id:1};
Paradox.engine.upgradeBuilding(data);
Removes a building for free from a city
const data:CityBuildingPointerType = {cityID: 1, id:1};
Paradox.engine.removeBuilding(data);
Sells a building and removes it from a city
const data:CityBuildingPointerType = {cityID: 1, id:1};
Paradox.engine.sellBuilding(data);
Building's templates
Create multiple templates at once
const data:TemplateBuildingDescType[] = [
{
id: 1,
name: "Castle",
levels: [
{
level: 1,
cost: [{resourceID: 1, amount: 100}],
prod: [{resourceID: 2, amount: 100}],
cons:[{resourceID: 2, amount: 2}],
sold:[{resourceID: 1, amount: 50}]
},
{
level: 2,
cost: [{resourceID: 1, amount: 200}],
prod: [{resourceID: 2, amount: 200}],
cons:[],
sold:[]
},
]
},
{
id: 2,
name: "Home",
levels: []
},
];
Paradox.engine.createBuildingTemplates(data);
Get all templates
Paradox.engine.getTemplateBuildings().then( (templates:TemplateBuilding[])=>{});
Import/export data
Import / restore game data
const data:GameSaveDescType = {
cities: [/* ... cities data */ ],
resources: [/* ... resources data */ ],
templateBuildings: [/* ... templates data */ ],
};
Paradox.engine.restoreGameData(data);
Save / export game data
Paradox.engine.saveGameData().then( (gameData:GameSaveDescType)=>{});
Process a cycle
Processes a cycle. A cycle means that productions are added to cities's wallets and consumptions are removed from them too.
Paradox.engine.doCycle();
Data Types used by the engine's core
The 'Resource' object
A resource object describes a resource with a name and a unique id.
// used by the engine
class Resource{
constructor(
public id:number = -1,
public name:string = "",
){}
}
The 'Quantity' object
The 'Quantity' object describes a certain amount for a specific resource, targeted by its id.
// used by the engine
class Quantity{
constructor(
public resourceID:number = -1,
public amount:number = 0,
){}
}
The 'QuantityList' object
The 'QuantityList' object describes a list of 'Quantity' objects.
// used by the engine
class QuantityList{
constructor( quantities:Quantity[] ){}
public set(quantities:Quantity[]):void{}
public get ():Quantity[]{}
}
The 'BuildingLevel' object
The 'BuildingLevel' object describes a building's level.
// used by the engine
class BuildingLevel{
constructor(
public level:number = 0,
public cost:QuantityList = new QuantityList([]),
public prod:QuantityList = new QuantityList([]),
public cons:QuantityList = new QuantityList([]),
public sold:QuantityList = new QuantityList([]),
){}
}
The 'Building' object
The 'Building' object describes a building at a certain level.
// used by the engine
class Building{
constructor(
public name:string = "",
public level:BuildingLevel = null,
public tplBuildingID:number = -1,
public id:number = -1,
){}
}
The 'TemplateBuilding' object
The 'TemplateBuilding' object describes a template which is used to create buildings.
// used by the engine
class TemplateBuilding{
constructor(
public id:number = -1,
public name:string = "",
public levels:BuildingLevel[] = [],
){}
}
The 'City' object
The 'City' object describes a template describes a city
// used by the engine
class City{
constructor(
public id:number = 0,
public name:string = "",
public buildings:Building[] = [],
public wallet:QuantityList = new QuantityList([])
){}
}
2 months ago
3 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago