Train configuration UI, bring back support for train names, baic train status speaking support

Author: ahicks92

locale/en/blueprints.cfg

@@ -113,3 +113,14 @@ train-stop-limit=Train limit
 train-stop-limit-disabled=unlimited
 train-stop-limit-invalid=Invalid limit, must be non-negative integer
 train-stop-trains-incoming=Trains incoming
+
+# Locomotive configuration
+locomotive-config-title=Locomotive Configuration
+locomotive-manual-mode=Manual mode
+locomotive-train-name=Train name
+locomotive-train-state=Train state
+locomotive-train-state-unknown=Train state unknown
+
+# Train states
+train-state-manual=Train in manual
+train-state-headed-to=Train headed to __1__

locale/en/entity-info.cfg

@@ -61,6 +61,9 @@ ent-info-resource-infinite=at __1__ percent
 # We let the game localise the ghost prototype name, as well.
 ent-info-ghost=__1__ of __2__
 
+# Rolling stock with train name
+ent-info-rolling-stock-of-train=__1__ of __2__
+
 ent-info-self-character=You
 
 ent-info-corpse-is-self=of your character

scripts/fa-info.lua

@@ -52,6 +52,7 @@ local RailDescriber = require("railutils.rail-describer")
 local RailAnnouncer = require("scripts.rails.announcer")
 local SurfaceHelper = require("scripts.rails.surface-helper")
 local RailQueries = require("railutils.queries")
+local TrainHelpers = require("scripts.rails.train-helpers")
 
 local mod = {}
 
@@ -1033,6 +1034,20 @@ local function ent_info_cargo_wagon(ctx)
    end
 end
 
+---Handler for announcing train state on rolling stock (low priority, runs last)
+---@param ctx fa.Info.EntInfoContext
+local function ent_info_train_state(ctx)
+   local ent_type = ctx.ent.type
+   if
+      ent_type == "cargo-wagon"
+      or ent_type == "artillery-wagon"
+      or ent_type == "locomotive"
+      or ent_type == "fluid-wagon"
+   then
+      TrainHelpers.push_state_message(ctx.message, ctx.ent)
+   end
+end
+
 ---@param ctx fa.Info.EntInfoContext
 local function ent_info_fluid_connections(ctx)
    local cursor_center = { x = ctx.cursor_pos.x + 0.5, y = ctx.cursor_pos.y + 0.5 }
@@ -1308,6 +1323,19 @@ function mod.ent_info(pindex, ent, is_scanner)
       or ent.type == "curved-rail-b"
    then
       -- For rails, skip entity name - rail classification will be announced by ent_info_rail handler
+   elseif
+      ent.type == "cargo-wagon"
+      or ent.type == "artillery-wagon"
+      or ent.type == "locomotive"
+      or ent.type == "fluid-wagon"
+   then
+      -- For rolling stock, include train name
+      local train_name = TrainHelpers.get_name(ent)
+      ctx.message:fragment({
+         "fa.ent-info-rolling-stock-of-train",
+         Localising.get_localised_name_with_fallback(ent),
+         train_name,
+      })
    else
       ctx.message:fragment(Localising.get_localised_name_with_fallback(ent))
    end
@@ -1484,6 +1512,9 @@ function mod.ent_info(pindex, ent, is_scanner)
    run_handler(ent_info_combinator_connections)
    run_handler(ent_info_circuit_network)
 
+   -- Train state handler (lowest priority, runs last)
+   run_handler(ent_info_train_state)
+
    return ctx.message:build()
 end
 

scripts/rails/train-helpers.lua

@@ -0,0 +1,106 @@
+--[[
+Helper functions for managing trains and rolling stock.
+Provides utilities for naming trains, identifying locomotives, and describing train state.
+]]
+
+local mod = {}
+
+---Get the identifying locomotive for a train (the one with the lowest unit_number).
+---This provides a stable reference point for train-level operations.
+---@param rolling_stock LuaEntity A rolling stock entity (locomotive, wagon, etc)
+---@return LuaEntity? The locomotive with the lowest unit_number, or nil if no locomotives
+function mod.get_identifying_locomotive(rolling_stock)
+   local train = rolling_stock.train
+   if not train then return nil end
+
+   local locomotives = train.locomotives
+
+   -- No locomotive can be both a front and back mover, so check each list separately
+   local identifying_loco = nil
+
+   -- Check front movers
+   if locomotives.front_movers then
+      for _, loco in ipairs(locomotives.front_movers) do
+         if not identifying_loco or loco.unit_number < identifying_loco.unit_number then identifying_loco = loco end
+      end
+   end
+
+   -- Check back movers
+   if locomotives.back_movers then
+      for _, loco in ipairs(locomotives.back_movers) do
+         if not identifying_loco or loco.unit_number < identifying_loco.unit_number then identifying_loco = loco end
+      end
+   end
+
+   return identifying_loco
+end
+
+---Set the name of all locomotives in a train.
+---@param rolling_stock LuaEntity A rolling stock entity (locomotive, wagon, etc)
+---@param name string The name to set
+function mod.set_name(rolling_stock, name)
+   local train = rolling_stock.train
+   if not train then return end
+
+   local locomotives = train.locomotives
+
+   -- Set name on all front movers
+   if locomotives.front_movers then
+      for _, loco in ipairs(locomotives.front_movers) do
+         loco.backer_name = name
+      end
+   end
+
+   -- Set name on all back movers
+   if locomotives.back_movers then
+      for _, loco in ipairs(locomotives.back_movers) do
+         loco.backer_name = name
+      end
+   end
+end
+
+---Get the name of a train.
+---@param rolling_stock LuaEntity A rolling stock entity (locomotive, wagon, etc)
+---@return string The train name (backer_name of identifying locomotive), or fallback
+function mod.get_name(rolling_stock)
+   local identifying_loco = mod.get_identifying_locomotive(rolling_stock)
+   if identifying_loco then return identifying_loco.backer_name end
+
+   -- No locomotive: fallback based on whether we have a train
+   local train = rolling_stock.train
+   if train then
+      return "id " .. train.id
+   else
+      return "unnamed train"
+   end
+end
+
+---Add train state information to a message builder.
+---@param msgbuilder fa.MessageBuilder The message builder to add fragments to
+---@param rolling_stock LuaEntity A rolling stock entity (locomotive, wagon, etc)
+---@return boolean True if state was added, false if no state to report
+function mod.push_state_message(msgbuilder, rolling_stock)
+   local train = rolling_stock.train
+   if not train then return false end
+
+   -- Check if in manual mode
+   if train.manual_mode then
+      msgbuilder:fragment({ "fa.train-state-manual" })
+      return true
+   end
+
+   -- Check if headed to a station
+   local path_end_stop = train.path_end_stop
+   if path_end_stop then
+      local station_name = path_end_stop.backer_name
+      if station_name and station_name ~= "" then
+         msgbuilder:fragment({ "fa.train-state-headed-to", station_name })
+         return true
+      end
+   end
+
+   -- No verbalizable state
+   return false
+end
+
+return mod

scripts/ui/entity-ui.lua

@@ -26,6 +26,7 @@ local equipment_grid_tab = require("scripts.ui.tabs.equipment-grid")
 local selector_combinator_tab = require("scripts.ui.tabs.selector-combinator")
 local arithmetic_combinator_tab = require("scripts.ui.tabs.arithmetic-combinator")
 local train_stop_tab = require("scripts.ui.tabs.train-stop")
+local locomotive_config_tab = require("scripts.ui.tabs.locomotive-config")
 
 local mod = {}
 
@@ -182,6 +183,9 @@ local function build_configuration_tabs(entity)
    -- Add train stop configuration
    if prototype.type == "train-stop" then table.insert(tabs, train_stop_tab.train_stop_tab) end
 
+   -- Add locomotive configuration
+   if prototype.type == "locomotive" then table.insert(tabs, locomotive_config_tab.locomotive_config_tab) end
+
    -- Future: Add other device-specific tabs here
    -- if prototype.type == "mining-drill" then ...
    -- if prototype.type == "lab" then ...

scripts/ui/tabs/locomotive-config.lua

@@ -0,0 +1,59 @@
+--[[
+Locomotive configuration tab.
+
+Provides a configuration form for locomotives with:
+- Manual/automatic mode toggle
+- Train name
+]]
+
+local FormBuilder = require("scripts.ui.form-builder")
+local TrainHelpers = require("scripts.rails.train-helpers")
+local UiKeyGraph = require("scripts.ui.key-graph")
+
+local mod = {}
+
+---@class fa.ui.LocomotiveTabContext: fa.ui.TabContext
+---@field tablist_shared_state fa.ui.EntityUI.SharedState
+
+---Render the locomotive configuration form
+---@param ctx fa.ui.LocomotiveTabContext
+---@return fa.ui.graph.Render?
+local function render_locomotive_config(ctx)
+   local entity = ctx.tablist_shared_state.entity
+   if not entity or not entity.valid then return nil end
+   assert(entity.type == "locomotive", "render: entity is not a locomotive")
+
+   local train = entity.train
+   if not train then return nil end
+
+   local builder = FormBuilder.FormBuilder.new()
+
+   -- Manual/automatic mode checkbox
+   builder:add_checkbox("manual_mode", { "fa.locomotive-manual-mode" }, function()
+      return train.manual_mode
+   end, function(value)
+      train.manual_mode = value
+   end)
+
+   -- Train name field
+   builder:add_textfield("name", {
+      label = { "fa.locomotive-train-name" },
+      get_value = function()
+         return TrainHelpers.get_name(entity)
+      end,
+      set_value = function(value)
+         TrainHelpers.set_name(entity, value)
+      end,
+   })
+
+   return builder:build()
+end
+
+-- Create the tab descriptor
+mod.locomotive_config_tab = UiKeyGraph.declare_graph({
+   name = "locomotive-config",
+   title = { "fa.locomotive-config-title" },
+   render_callback = render_locomotive_config,
+})
+
+return mod