Privus API is an add-on/library for Sid Meier's Civilization VII that aims to create a simple and unified modding API in order to signficantly ease the modding development process (especially when it comes to UI) and solve a few major problems with the traditional modding process in Civilization VII:
Default locations for the mods folder:
Import the category of whatever UI component you wish to modify
(The file to import from is listed under the component's API reference)
Create a class that implements the API your desired functionality
(You can see all the API functions you can implement in the API reference)
Register your class with the Privus API using your mod's id
The full example mod can be seen in examples/pause-menu
Compatibility
This API solves the inherent mod incompatibility by allowing mods to:- Implement changes to much more specific aspects of the UI
- Be aware of any other mods (through their mod ids) that have implemented the same changes/functions
- Use the default game functionality as desired
- Not have to replace any original files of the base game
Complexity
This API reduces the complexity and tediousness of mod development by allowing modders to only have to implement the exact changes they want and to not have to reimplement any of the base game functionality.Legality
This API avoids copyright issues by not copying nor distributing any of the base game's source code; Any default/base game functionality is re-implmeneted using original source code.Features
- Ability to easily modify both general UI components and tooltips
- Centralized modder-customizable mod options within the game's option menu.
- Complete control over the game's default functionality.
- Significantly easier compatibility with other mods with similar functionality
- Ability to see other active mods and which API functions they have implemented.
- Standardized and well-documented functions and members
- Simple and concise API and function definitions
- Access to fine-grained UI functionality within the game
Installation
Automatic
Manual
Download the.zip or .tar.gz source code from the github releases and extract the archive into the mods folder.Default locations for the mods folder:
- Windows:
%localappdata%\Firaxis Games\Sid Meier's Civilization VII\Mods - Linux/Steam Deck:
~/My Games/Sid Meier's Civilization VII/Mods/ - MacOS:
~/Library/Application Support/Civilization VII/Mods
Quickstart
Add the Privus API as a dependency in your modinfo
XML:
<Dependencies>
<!-- Other dependencies... -->
<Mod id="privus-api" title="Privus API"/>
</Dependencies>Import the category of whatever UI component you wish to modify
JavaScript:
//I want to modify the pause menu
import PauseMenuCategory from '/privus-api/ui/pause-menu/privus-pause-menu.js';Create a class that implements the API your desired functionality
JavaScript:
class MyPauseMenu {
//Other functions...
//I want to change the game info in the pause menu
renderUIGameInfo(modIds, gameInfo) {
//...
}
}Register your class with the Privus API using your mod's id
JavaScript:
PrivusControls.defineModClass('my-mod', PauseMenuCategory, MyPauseMenu);Repeat the process for any other UI components you want to modify.
Example
This single script file changes the map seed text and game info text in the pause menu
JavaScript:
import PauseMenuCategory from '/privus-api/ui/pause-menu/privus-pause-menu.js';
class ExamplePauseMenu {
//'root' is the ComponentRoot of this element
constructor(root) {
this._root = root;
}
//Change the map seed info text
renderUIMapSeed(modIds, mapSeedInfo) {
console.info(`[EXAMPLE-PAUSE-MENU] Mods that have already overriden the map seed ui: ${modIds}`);
//You can also get the map seed info using `this._root.querySelector(...)`
if (!mapSeedInfo) throw new Error('Could not find map seed element!');
mapSeedInfo.textContent = `<Example Map Seed>`;
}
//Change the game info text
renderUIGameInfo(modIds, gameInfo) {
console.info(`[EXAMPLE-PAUSE-MENU] Mods that have already overriden the build info ui: ${modIds}`);
if(!gameInfo) throw new Error('Could not find game info element!');
gameInfo.textContent = `<Example Game Info>`;
}
}
// Register our class as this mod's changes to the pause menu
PrivusControls.defineModClass('example', PauseMenuCategory, ExamplePauseMenu);API Reference
All current API functions and their details are laid out in the wiki