Project Structure

FreeSO is a very complicated project with many different project "groups", and different projects within them. This page will go through all the projects in FreeSO, what they are used for and any other notable information about them.

It's recommended that you start working on FreeSO in one specific area, rather than overwhelming yourself by looking at the whole thing.

FreeSO Client

Projects relating directly to the FreeSO Client application, or the Volcanic IDE. .

• FSO.Windows - Startup project for desktop versions of FreeSO. Contrary to the name, it is also used on Linux and OSX, though it could eventually be replaced with specific builds for those platforms.
• FSO.iOS - Defunct iOS project.
• FSO.Droid - More defunct Android project.
• FSO.IDE - The Volcanic IDE. This Windows Forms project injects a variety of development tools generally relating to the SimAntics lot environment, such as a full object and script editor / debugger. When this project is started, the volcanic window will appear when joining any lot, and hook into the SimAntics VM.
• FSO.Common - A lot of stuff used between many projects. Could use some cleanup.

SimAntics

Projects used to run the simulation itself. Properties in The Sims (1/Online) run on top of a virtual machine using a scripting language called SimAntics, which drives object and sim behaviours ingame.

• FSO.SimAntics - The most complicated part of the game - the SimAntics virtual machine.
  • Engine contains core classes for VM behaviour and execution.
  • Entities contains the classes that represent game objects or sims (which are pretty complicated).
  • Primitives are instructions that are used within SimAntics scripts.
  • NetPlay handles all user interaction between the player and the virtual machine, using a serializable command system that can be sent over a network. Clients are given a full VM state to start, then run the same sequence of ticks as the server to stay in sync.
    • EODs are TSO specific "mini-servers" that drive smaller interactive experiences that appear in the user interface (external/embedded object display). These include game logic for objects like the signpost, blackjack table, and the entire nightclub job. The client interacts with these through UI placed in the Live Mode panel, classes for these can be found in the FSO.Client.UI.Panels.EODs namespace. For more information, check out https://freesoeod.wordpress.com/ .
  • Marshals contains marshalled structs for all VM state. When saving a VM, its classes are marshaled using these classes, then serialized to disk to save the property (VMMarshal). This is also used to send current lot state to someone joining or re-synchronizing with a property when online.
  • Model contains data classes and enums that the VM uses during execution, such as roommaps, routing state and terrain data.
  • Utils contains helpful classes that can be used to bootstrap a VM, such as the world activator. There is also a class for performing Architecture actions like drawing walls, called "VMArchitectureTools".
• FSO.SimAntics.JIT - An experimental project that transpiles SimAntics to C#, to use as a replacement for the interpreter. Generally works much faster but is still in experimental stages.
• FSO.SimAntics.JIT.Roslyn - A roslyn backend for compiling transpiled SimAntics functions at runtime, and then dynamically loading them as modules. Still experimental, but works.

Lot Rendering

FSO.LotView is used to render properties ingame. It supports 2D (isometric), 2D Hybrid (rotatable isometric) and 3D rendering modes, and eventually will include the possibility to mix and match 3D objects in 2D mode.

Typically each VM has a world. Control of displaying this world is done with the WorldState. The world is split into 3 parts, WorldArchitecture (walls/floors), WorldEntities (avatars/dynamic objects) and WorldStatic (static objects). WorldStatic is only used in 2D mode, and is a way to avoid drawing sprites that do not change frequently every frame by drawing them to a static buffer that isn't updated often.

• Components: Each SimAntics entity has its own world representation (called a Component) that is updated with graphic changes, position, rotation, container information and more. Many larger scale constructs, such as walls, floors and roofs are managed by their own components that are rendered with a single call. Components can also draw other worlds via the SubWorldComponent, which is how surrounding properties are drawn in FreeSO.
• Effects are essentially shaders used by different components and parts of the renderer. These are abstractions over Monogame effects that make it easier to set effect parameters without string lookup.
• Facade contains utilities for generating 3D lot facades - essentially simplified 3d models that can be used to represent a lot on a city or neighbourhood view. You can imagine these as very simple LOD models.
• LMap contains classes relating to the lighting system that FreeSO uses (stands for "lightmap"). The game generates large 2d lightmaps for each floor, drawing each light with shadowing from walls and objects. This can optionally use 3d models to draw shadows.
• Model contains a lot of data related classes and enums used by the components and other classes.
• Platform contains implementations for behaviours that are different between "modes" of the renderer, such as 2D and 3D mode. For example, object hit detection must be done a different way in 3D mode, as in 2D mode it draws 2D sprites for a given pixel to determine the exact object that was clicked/hovered.
• RC stands for "reconstruction", and was the original name for the 3D mode as it uses 3D reconstructed models.
• Utils contains a bunch of stuff that should probably be in Model, and rendering utilities such as the SSAA downsampler.

Content Service

The content service provides access to all of The Sims (1/online) files and file formats, in a way that the game can easily use and understand.

• FSO.Files - File format readers and writers.

  • FAR archives (v1, v3) are essentially archives that contain game resources of many different filetypes, and allow lookup via ID or filename. These are usually compressed. These are scanned when the game first loads, and their data is dynamically streamed into the game as files out of them are requesated.
  • Formats.Iff is where you'll find the most complexity, containing all resources used by the SimAntics engine for houses, objects, walls and floors.
    • Iff Chunks are specifically formatted data that can be found in an iff file, with a unique identifying id+chunk type combination. These can range from object graphics (SPR2, OBJ2) to object scripts (BHAV, TREE) to TS1 house data (ARRY, OBJM). Each of these chunks are only parsed when they are requested from the iff - before this point they are just in memory.
    • PIFF is a custom format that allows patches to be applied to IFFs, to either modify data in existing chunks, remove chunks entirely or add new ones. This is the mechanism that allows us to patch existing game resources without redistibuting any of the copyrighted content with our changed file - only the changes are included with the game client.

• FSO.Content - Content providers for various parts of the client. From UI to Objects to Sounds,

  • Content information can be from multiple sources, FAR (v1, v3) files, the filesystem, packingslips or even sourced at runtime. This information is all loaded when the game starts up (without loading the content itself), so that it can be quickly located and loaded when it is needed later on.
  • The FAR(1/3)Provider is by far the most used provider class in the game. It uses a TimedReferenceCache that essentially abuses WeakReferences to detect when a game resource has went unused for a long period of time, and unloads it when not needed. This is unfortunately very messy and unstable, so it would be nice to change. Note that basically every class in the game uses the content provider, so you'll have to be careful if making changes to the core of it.
  • 3D Meshes are also provided using a content provider, though it behaves unlike any other content provider. When a mesh is requested for a given DGRP+OBJD, we check the iff, mesh replace, and mesh cache in order for any existing models to use. When none are available, we fire up the mesh reconstruction by creating a new DGRP3DMesh. This will signal when it is ready via an attached boolean Rendered property in each DGRP3DGeometry (until it is ready, the model will be missing ingame. When 3D models are loaded, they are loaded with their textures for good, meaning that they can cause you to run out of memory. This is another point that needs improving.

Audio

• FSO.HIT - HIT is the sound VM that is used in The Sims (1/Online), which aims to hid complex sound logic (handled using a bytecode language) behind simply calling "events" with attached owners. We implement a simple interpreter to play back audio in the same way the original game does, but it is missing a lot of features, and the loading and choosing of events is less than ideal in TSO due to restructuring Maxis did during development (it is better in TS1).
  • It is very easy to arbitrarily play a sound event. HITVM.Get().PlaySoundEvent("event") is a quick way to play a sound at the default volume without a source (eg. UI sounds).

Character Rendering

Projects used to draw characters ingame. Nowadays, all of the skinning is done on the GPU using vertex shaders, though you might find some remnants of CPU skinning in there.

• FSO.Vitaboy - File formats and structures relating to ingame characters, and the rendering of them.
• FSO.Vitaboy.Engine - A set of classes that can be used to render and animate characters in FreeSO.

UI

A good place to start if you want to add new UI elements to FreeSO.

• FSO.Client - Class library containing all FreeSO specific client behaviour. This is the home of all FreeSO UI elements, screens, controllers and so on. It is essentially the front end for FreeSO.
  • Screens are ui elements that command control over the entire game. Only the first few menus count as different screens; as soon as you join the city, you will be using the CoreGameScreen. (SandboxGameScreen for sandbox mode). Screens contain multiple Panels, which can contain more panels and elements.
  • Controllers are logic that can be attached to screens and panels to drive game behaviour. Typically, we attach controllers to Screens and Panels that handle interaction with the game servers using connection Regulators. These controllers typically handle a subset of actions that a specific panel or screen will do. These can usually be obtained using UIElement.FindController<T>().
• FSO.UI - A more core subset of UI elements that is used between both FreeSO and Simitone. This includes simple things like text labels, buttons, images, text edits etc.
• FSO.Patcher - The patcher utility that the game starts to patch in changes made via updates. These are generated and distributed by the game server, which can provide either "full" or "delta" updates, the latter only containing the files that changed since the last version. Multiple delta updates can be applied in a row, saving the user from redownloading the entire game each time.

FSOFacadeWorker

A utility to render 3D lot thumbnails for a FreeSO server. Interacts with its API (given an admin login) to retrieve and load lots that need new 3D thumbnails, then generate and upload them. This project requires graphics acceleration to run, and is likely to run out of memory after a certain number of properties processed due to leaks in the content service, GPU resource mangement and a strict 32 bit memory limit.

For a quick way to view the produced FSOF files, check out https://riperiperi.github.io/FSOFLoader/ .

Server

The meaty part. A lot of this has been split into separate projects so that they can be included in the client without including more ridiculous things like the lot containers.

• FSO.Server.Core - The main server executable. This currently runs with .NET Core 2.2, and uses FSO.Server as a class library. It injects FSO.Server.Api.Core as the API server to use ASP.NET Core.
• FSO.Server - The server's core logic. This includes logic for each server (Lot/Task/City), its data service provider, Aries/Voltron/Electron protocol hosting and packet handlers for each server.
• FSO.Server.Api.Core - ASP.Net Core server that handles the HTTP api server, used for authentication, external data requests and administration. This replaces FSO.Server.Core and we're definitely looking for reasonable improvements and expansion.
• FSO.Server.Api - Old ASP.Net (not core) server, now defunct.
• FSO.Server.Database - Data representation and access from the MySQL server (via the DA classes). Also includes DatabaseScripts used for initializing and updating the database.
• FSO.Server.Debug - Old project for tracking data sent to and from the server, via a Windows Forms UI. Was originally used alongside testing with the original TSO.
• FSO.Server.Domain - Currently contains management for Shards (cities).
• FSO.Server.Watchdog - Contains some basic logic to update a server after it has closed. The server places the update file in a relative folder, the watchdog finds it, then it extracts it. Pretty simple.

Client-Server shared projects

Projects used to drive communication between the client and server.

• FSO.Server.Clients - Classes used to connect to server/clients using the FreeSO/TSO protocols.
• FSO.Server.Common - Common utilities that the server and client use for communication.
• FSO.Server.Protocol - The protocol which the client and server use to communicate.
  • Aries is the base protocol that was used by The Sims Online, and many other online games of the time period.
  • Voltron is the Sims Online specific protocol that was used to communicate with the original game. Only packets compatible with the original game should go in here.
  • Electron is a FreeSO specific protocol that extends on top of Voltron for new features, or to replace features that were not reverse engineered from TSO. Currently, most packets are within here, including all communication done when joining and playing lots.
  • Gluon is a FreeSO specific protocol that is used for communication between servers. Servers authenticate with each other using a secret key, and can send over specific information such as requests to open properties (City -> Lot), requests to send mail to players (Lot/Task -> City) and so on.
  • CitySelector contains XML format requests and responses used by the city selector servlet.
• FSO.Common.DatabaseService - The database service is used for direct "database" requests, which are never cached in memory.
• FSO.Common.DataService - The database service is used for direct "data service" requests, which are data structures that are cached in memory for quicker access. This includes most objects available in the city, such as Avatars, Lots and Neighbourhoods. This system itself is pretty complicated, and new structures must be added to the data service definition file using Volcanic.
• FSO.Common.Domain - Includes classes for domain specific functions of the server, such as Realestate (lot pricing and neighbourhoods), Shards (cities and city data) and the Top100.

Defunct

• FSO.Debug - A precursor to Volcanic (and the action queue) that allowed basic examination and control over running trees and actions. It is slated to be removed.

External Projects (with changes)

• Lidgren.Network.WindowsGL - Networking framework used by Monogame. Not used in FreeSO, but may be used by dependants.
• Mina.NET - A .NET port of the Apache Mina networking library. We use a fork called FSOMina.NET to fix a few bugs, though at this point it might be worth swapping out entirely.
• Monogame.Framework.Windows - The Monogame framework is used for all rendering, sound and a ton of vector math. We have a specific fork of Monogame called FSOMonogame, which contains a few small fixes and changes for performance reasons.
• Monogame.Framework.Linux - Versions of monogame for other platforms are also built, as they are distributed with the FreeSO client and switched between depending on what platform the game is started on.
• Monogame.Framework.WindowsGL - Ditto - OpenGL version of Monogame.
• Monogame.Framework.Net.WindowsGL - Contains some additional functions that allow use of the onscreen keyboard (for mobile platforms, unused)
• Monogame.Framework.Content.Pipeline.Windows - Used directly by MSDFExtension, which is used to build the MSDF fonts in the game.
• Mp3Sharp - A managed Mp3 decoder. This is used to play music ingame - it is sent chunks of Mp3 to decode, and they are played via FSO.Common.Audio.MP3Player.
• SimplePaletteQuantizer - A library for quantizing imported sprite images into a limited colour palette. (256 colours) Many of the quantizers and dithering patterns do not work, but the selection used in Volcanic seems to work "well enough".
• TargaImage - A library for reading TGA files, as many of The Sims Online UI elements are in this format.
• TargaImagePCL - A PCL version of the library for reading TGA files, which does not use System.Drawing. Needs a bit more work to fully replace TargaImage.
• VoronoiLib - A library for creating a voronoi tesselation of a given point cloud. Used for visualizing neighbourhood boundaries.

Fonts

Fonts in FreeSO used to be rendered using Monogame's internal system, but were switched to a custom system for sharper rendering at variable size, and more control over the fonts themselves (to support fallback fonts, and potentially builtin emojis).

• MSDFExtension - An extension for the Monogame Content Pipeline that allows the generation of "MSDF fonts", or "muitiple signed distance field". This way of representing characters allows resolution independant scaling that keeps sharp corners and edges at any resolution.
• MSDFData - The data format and helper functions for obtaining MSDF format characters, as well as storing font information such as kerning pairs.