Skip to content

Game.ITaxSystem

Assembly: Game
Namespace: Game.Simulation

Type: Interface

Base: — (interface)

Summary:
Interface that defines the contract for the city's taxation system. Implementations are responsible for storing and exposing tax rates (global and per-area/industry), providing tax parameter data, computing tax effects, and estimating tax income based on city statistics. The interface is designed to integrate with Unity's Job System (JobHandle) and uses native collections for efficient estimate calculations in a multithreaded simulation environment.

Fields

  • This interface declares no fields.
    Implementations may have internal fields to store rates, cached parameters, or job handles, but those are not part of the interface contract.

Properties

  • public int TaxRate { get; set; }
    Global/default tax rate property. Implementations should expose a get/set for a base tax rate which can be used as a fallback or default for areas/units that don't have a specific rate configured.

  • public Unity.Jobs.JobHandle Readers { get; }
    Read-only JobHandle used to track jobs that read tax-related data. Exposing a JobHandle allows systems using the tax system to properly synchronize with Unity's Job System (for example, to ensure reads complete before writes begin or vice versa).

Constructors

  • Interfaces do not define constructors.
    Concrete implementations will provide constructors or factory methods according to the mod's architecture.

Methods

  • TaxParameterData GetTaxParameterData()
    Returns a TaxParameterData structure (implementation-specific) which contains parameters used by tax calculations (for example, thresholds, modifiers, or base multipliers). Use this to retrieve the tuning data used by the system.

  • int GetTaxRate(TaxAreaType areaType)
    Returns the configured tax rate for the given TaxAreaType. TaxAreaType typically differentiates between residential, commercial, industrial, office, or other area groupings used by the simulation.

  • void SetTaxRate(TaxAreaType areaType, int rate)
    Sets the tax rate for the provided area type. Implementations should validate rate ranges where appropriate.

  • int2 GetTaxRateRange(TaxAreaType areaType)
    Returns the allowed range (min/max) of tax rates for the given area type as an int2 (x=min, y=max). Useful for UI clamping and validation.

  • int GetResidentialTaxRate(int jobLevel)
    Returns the tax rate applied to a residential tier/level (jobLevel typically maps to education/job tier).

  • void SetResidentialTaxRate(int jobLevel, int rate)
    Sets the tax rate for a particular residential job/education level.

  • int GetCommercialTaxRate(Resource resource)
    Returns the tax rate for commercial buildings associated with the given Resource (for example, different commercial sizes or specialization resources).

  • void SetCommercialTaxRate(Resource resource, int rate)
    Sets the commercial tax rate for the specified Resource.

  • int GetIndustrialTaxRate(Resource resource)
    Returns the tax rate for industrial buildings for a given Resource (resource often represents specialization such as forestry, mining, etc.).

  • void SetIndustrialTaxRate(Resource resource, int rate)
    Sets the industrial tax rate for the specified Resource.

  • int GetOfficeTaxRate(Resource resource)
    Returns the tax rate for office-type buildings, possibly specialized by Resource.

  • void SetOfficeTaxRate(Resource resource, int rate)
    Sets the office tax rate for the specified Resource.

  • int GetTaxRateEffect(TaxAreaType areaType, int taxRate)
    Calculates and returns the "effect" (modifier/penalty/impact) of applying the supplied taxRate to the given area type. This is typically a deterministic mapping used by the simulation to modify behavior (e.g., demand, happiness, or population change) when tax rates change.

  • int GetEstimatedTaxAmount(TaxAreaType areaType, TaxResultType resultType, NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup, BufferLookup<CityStatistic> stats)
    Estimates total tax income for the specified area type and result type using provided city statistics. The two native parameters:

  • statisticsLookup: a NativeParallelHashMap mapping statistics keys to entities.

  • stats: a BufferLookup of CityStatistic buffers attached to those entities. This method is intended to be safe for calling from jobs (hence the use of native collections) and should perform a fast aggregate estimate.

  • int GetEstimatedResidentialTaxIncome(int jobLevel, NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup, BufferLookup<CityStatistic> stats)
    Estimates residential tax income for a specific job/education level using the provided statistics lookup and buffers. Returns the estimated income as an integer.

  • int GetEstimatedCommercialTaxIncome(Resource resource, NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup, BufferLookup<CityStatistic> stats)
    Estimates commercial tax income for the given resource/specialization.

  • int GetEstimatedIndustrialTaxIncome(Resource resource, NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup, BufferLookup<CityStatistic> stats)
    Estimates industrial tax income for the given resource/specialization.

  • int GetEstimatedOfficeTaxIncome(Resource resource, NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup, BufferLookup<CityStatistic> stats)
    Estimates office tax income for the given resource/specialization.

Notes on estimated-income methods: - These methods expect the caller to supply the necessary statistics lookup and buffer accessors. This design lets implementations be used from worker jobs without dereferencing managed collections. - Returned values are integer estimates; rounding/truncation rules depend on implementation. - Implementations should avoid long-running work here; they are intended to be cheap aggregates for UI and planning.

Usage Example

// Example: minimal ITaxSystem implementation sketch
public class SimpleTaxSystem : ITaxSystem
{
    private int[] residentialRates = new int[3];
    private NativeList<int> dummyList; // placeholder for required native resources

    public int TaxRate { get; set; }
    public JobHandle Readers { get; private set; }

    public SimpleTaxSystem()
    {
        TaxRate = 10; // default
        Readers = default;
    }

    public TaxParameterData GetTaxParameterData()
    {
        return new TaxParameterData(); // return default/tuned values
    }

    public int GetTaxRate(TaxAreaType areaType) => TaxRate;
    public void SetTaxRate(TaxAreaType areaType, int rate) => TaxRate = rate;
    public int2 GetTaxRateRange(TaxAreaType areaType) => new int2(0, 100);

    public int GetResidentialTaxRate(int jobLevel) => residentialRates[jobLevel];
    public void SetResidentialTaxRate(int jobLevel, int rate) => residentialRates[jobLevel] = rate;

    public int GetCommercialTaxRate(Resource resource) => TaxRate;
    public void SetCommercialTaxRate(Resource resource, int rate) { /* store per-resource */ }

    public int GetIndustrialTaxRate(Resource resource) => TaxRate;
    public void SetIndustrialTaxRate(Resource resource, int rate) { /* store per-resource */ }

    public int GetOfficeTaxRate(Resource resource) => TaxRate;
    public void SetOfficeTaxRate(Resource resource, int rate) { /* store per-resource */ }

    public int GetTaxRateEffect(TaxAreaType areaType, int taxRate)
    {
        // Example: higher tax reduces desirability linearly
        return math.clamp(100 - taxRate, 0, 100);
    }

    public int GetEstimatedTaxAmount(TaxAreaType areaType, TaxResultType resultType,
        NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup,
        BufferLookup<CityStatistic> stats)
    {
        // Simplified: call specific estimators
        switch (areaType)
        {
            case TaxAreaType.Residential:
                return GetEstimatedResidentialTaxIncome(0, statisticsLookup, stats);
            default:
                return 0;
        }
    }

    public int GetEstimatedResidentialTaxIncome(int jobLevel,
        NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup,
        BufferLookup<CityStatistic> stats)
    {
        // Example stub: real implementation would traverse statistics and aggregate population * rate
        return 1000;
    }

    public int GetEstimatedCommercialTaxIncome(Resource resource,
        NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup,
        BufferLookup<CityStatistic> stats) => 500;

    public int GetEstimatedIndustrialTaxIncome(Resource resource,
        NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup,
        BufferLookup<CityStatistic> stats) => 300;

    public int GetEstimatedOfficeTaxIncome(Resource resource,
        NativeParallelHashMap<CityStatisticsSystem.StatisticsKey, Entity> statisticsLookup,
        BufferLookup<CityStatistic> stats) => 400;
}

Notes: - Replace stubbed logic with real aggregation over CityStatistic buffers and proper synchronization with Readers job handle when integrating into the simulation. - Validate rates against GetTaxRateRange to ensure UI and systems remain consistent.