Skip to content

RitnLibForce

A short view over a LuaForce. Gives access to the force's recipes and technologies (as chainable wrappers), production statistics, per-surface chart visibility and chart tags.
Source classes/LuaClass/RitnForce.lua
Stage control (runtime)
Access global — injected into _G by core/setup-classes.lua. No require.
Inherits from — (base class)
Extended by consumer subclasses, e.g. RitnCoreForce (see ADR-0001)
object_name "RitnLibForce"

Constructor

RitnLibForce(force) → RitnLibForce

Validates the input then freezes the fields. Rejects an input that is not a valid LuaForce.

Parameters - force :: LuaForce — the force to wrap.

Return value → RitnLibForce. On invalid input, isPresent is false.

local rForce = RitnLibForce(game.forces["player"])

Note — Most often obtained via RitnLibPlayer:getForce() or RitnLibEvent:getForce().

Attributes

All read-only ([Read]), frozen at construction.

force :: LuaForce [Read]

The wrapped LuaForce (live reference).

name :: string [Read]

Force name ("player", "enemy"…).

index :: uint [Read]

Force index.

items_launched :: table<string, uint>? [Read]

Items launched in rockets (item→count dictionary). Still available in Factorio 2.0.

rockets_launched :: uint? [Read]

Number of rockets launched.

FORCE_ENEMY_NAME :: "enemy" [Read]

Enemy force name constant.

FORCE_PLAYER_NAME :: "player" [Read]

Player force name constant.

FORCE_NEUTRAL_NAME :: "neutral" [Read]

Neutral force name constant.

isPresent :: boolean [Read]

false if the constructor rejected its input. Test it as a guard.

Methods

:getRecipe(recipe_name) → RitnLibRecipe

Returns a RitnLibRecipe wrapping the named recipe of this force.

Parameters - recipe_name :: string — recipe name.

Warning — Raises an error (error) if the recipe doesn't exist for this force. Make sure of the name beforehand.

RitnLibEvent(e):getPlayer():getForce():getRecipe("electronic-circuit"):setEnabled(false)

:getTechnology(tech_name) → RitnLibTechnology

Returns a RitnLibTechnology wrapping the named technology.

Parameters - tech_name :: string — technology name.

Warning — Raises an error if the technology doesn't exist for this force.

RitnLibEvent(e):getPlayer():getForce():getTechnology("ritn-tech-lumberjack").technology.researched = true

:setHiddenSurface(surfaceIdentification, value?) → RitnLibForce

Hides or shows a surface for this force on the chart. Chainable.

Parameters - surfaceIdentification :: SurfaceIdentification — the target surface. - value :: boolean? — true to hide (default), false to show.

rForce:setHiddenSurface(rSurface.name, true)

:countPlayers() → integer

Number of players in this force (#self.force.players).

:getChartTag(tag_number, surface_name, position) → LuaCustomChartTag?

Looks up a chart tag by its tag_number at a given position.

Parameters - tag_number :: uint — id of the tag to find. - surface_name :: string|LuaSurface — the surface. - position :: MapPosition — the position (must have .x and .y).

Warning — Builds a degenerate area {position, position} for find_chart_tags; may miss a tag due to float rounding.

Production statistics — :getStatsProduction · :getStatsProductionItem · :getStatsProductionFluid · :getStatsCount · :getStatsCountKill · :getStatsCountBuild

Return production / kill / build counts (integer?).

Warning — These methods depend on self.stats, currently disabled: its constructor block reads the Factorio 1.x statistics API, removed in 2.0. On a base instance they raise; a subclass must populate self.stats. Details and migration plan: Factorio 2.0 migration.

Usage examples

Disable recipes for a force (RitnElectronic/modules/electronic.lua):

RitnLibEvent(e):getPlayer():getForce():getRecipe("radar"):setEnabled(false)
RitnLibEvent(e):getPlayer():getForce():getRecipe("inserter"):setEnabled(false)

Force a technology as researched (RitnLumberjack/modules/lumberjack.lua):

RitnLibEvent(e):getPlayer():getForce():getTechnology("ritn-tech-lumberjack").technology.researched = true

Hide a surface on the chart (RitnCoreGame/modules/force.lua):

local rForce = RitnCoreForce(rEvent.force)
rForce:setHiddenSurface(rSurface.name, true)

Remarks

  • Temporary wrapper — never store the instance in storage; rebuild it in each handler. See Temporary wrappers.
  • getRecipe / getTechnology raise — they error() if the name doesn't exist. Prefer a name you're sure of, or guard the call.
  • getStats* pending 2.0 migration — see the warning above and Factorio 2.0 migration.

See also