SWGEmu – Mods Need Math and So Do You!

It’s hilarious how many times in my life I have been wrong, despite thinking at the time that I couldn’t be anything but right. “Android? Yeah, that will probably be like all the other Linux distros and won’t really catch on. Blackberry is where it’s at!”… “Algebra? Seriously, when am I ever going to actually use that in my daily life?”…


There’s a whole humorous train wreck of “wrong” in my past musings, but I did “call” a few things correctly over the years too, so it’s not all bad I guess. Still, as a person who enjoys programming and who doesn’t live under a rock, I have to admit that the above two visionary assessments of the future were pretty funny.

When it comes to math and modding SWGEmu, my latest project takes the cake for being thoroughly annoying in its need for math. You see, after building and testing a couple completely different ways to add player housing to NPC cities (which are noted here and in the GitHub repo for Legend of Hondo Classic), I decided that for myself and others it would be nice if I created a system that uses sites, plots, and layouts to make for easy and consistent city building. As a result, I needed to figure out the math that would ensure all structures on a site were placed correctly, no matter where the site is and what direction it is facing.

Unlike working with Blender, where the “engine” takes care of the math for you by way of allowing you to “parent” objects, SWGEmu doesn’t have such a feature for linking buildings together into groups. If you want to place a group of buildings relative to each other, you either place them that way manually or you calculate it manually and load them with a script. That’s fine really, but it’s not enough to accomplish what I wanted. I needed to come up with a way to essentially parent a set of buildings to a center point, such that an admin only needs to enter the world x, y, and heading (angle) of the site into the setup script and choose his desired layout to configure a site. The players would then go about picking which buildings they want to use, from the list of ones the admin made available. It sounds easy and I am certain that for someone who stuck with college math long enough, it would be easy, but I had a heck of time researching and coming up with something that works.

This is what I have…

Each site has a number of plots. The center (or “origin”) point of the site is the imaginary point all buildings are placed in reference to. The site config tables only consist of the x,y,angle,ow,oy, and layout name, making them super easy to setup. Here is an example of the location table for Tatooine,

tatooine_locations = {
  { — Site 1
    layout = “tatooineEstateSmall”,
    center = {x = -2697.4, z = 5, y = 2335.85, angle = -108, ow = -0.587785, oy = 0.809017},

A site can have one or many plots, with each plot being the home of a single building. Plots are noted in the config table by the x,y position of their center relative to the origin of the site. This is called their “local position”.

Layouts are the footprint of a site, comprised of the position of each plot and the buildings available on each plot. I’ve pre-made somewhere around twenty layouts of various types, but it’s easy to add more. The idea with using layouts is that using them removes an enormous amount of redundancy from the config files, while still allowing the admin a large amount of customization options (by editing existing layouts or adding new or modified ones). You can make one layout once and then use it in fifty different locations, for instance. Here is an example of a layout (pardon the jpg, but my blog theme doesn’t respect the code element…),

Each site is managed by a single terminal that sits on the road side of the site. It’s position is noted as 0x, #y from the origin of the site. Players use this terminal to purchase buildings at the site.

A visualization of the situation.

A visualization of the situation.

To ensure that buildings are located correctly when rotating a site, I needed to do the following math.

EDIT: Well I’ll be a monkey’s uncle! In the process of writing this post, I had an epiphany – in lua math.cos() returns a radian value, which I had to turn back into degrees with math.deg(), but… I had been feeding it degree values in my calculations! That’s why the rotation matrix math wasn’t working! What’s more, when it I fixed it in the math I had been using that mostly worked, said math stopped working. I just finished testing the rotation matrix math using degrees -> radians and it works exactly as it should!

1. We use a rotation matrix to the determine new world position of the center of each plot, where childX/childY is the x,y offset value from the site center and orgX/orgY is the world x,y of the site center. This is SO MUCH BETTER than what I had cobbled together before and it’s only slightly off due to the way SWGEmu applies angle values as integers rather than floats.

function HondoHousingSystem:getWorldPosition(angle, childX, childY, orgX, orgY)
    angle = math.rad(angle)

    local x = (math.cos(angle) * childX) + (childY * math.sin(angle))
    local y = (math.cos(angle) * childY) – (childX * math.sin(angle))

    x = x + orgX
    y = y + orgY

    return x, y

2. Next, we apply any local rotation to the angle value. By default (most…) buildings would be spawned with the doors facing to the north of the site. So if we want the door to be facing 90 left from the site north, we just add -90 to angle value we calculated earlier.

local rotation = SiteAngle + localRotation

With that bit of math, I was able to have the computer do all the heavy lifting of computation, allowing we lowly humans to easily create layouts by simply loading up the “simple” testing planet, which is conveniently flat at world 0,0, and placing structures where/how we’d like then noting their x,y locations. That’s actually one of the places where I use my custom slash command /hondo admin getBuildingInfo log, because it spits out the x, y, ow, oy, and angle data into a handy file on the server. The ow, and oy quaternion values are needed to properly rotate the terminal.

I’ve spent a lot of time working on this housing stuff, more than I really need to for my own purposes with Legend of Hondo, because I figured that I may as well make a system that is as useful to others as it would be to myself. With my focus now being on “adding to default SWGEmu” rather than simply modding it, I’ve been forced to consider things from a new perspective. While there is a lot of stuff that default SWGEmu can do, there’s also a considerable amount of code that actively prevents it from doing something it wasn’t designed to do. Placing temporary structures is a good example – sure you can load them in a lua script using the spawnBuilding() function (which erroneously fails to apply the angle btw), but the building will be automatically deleted by the server’s structure maintenance system, if you’ve spawned it using an owner that isn’t a player (such as tying it to an NPC, because you don’t want it to belong to a player). And, lot of other things like that, which either need to be modded away or “coded around”, by making nearly redundant functionality that does exactly what you need it to do. So when combined with my own iteration and testing of various ways one can solve the “player housing in an NPC city” problem, the process has been and remains long.

As of today, I have completed the layout and config system, created some layouts, made the system that spawns temp buildings on a site until the player buys one, and a slash command for an admin to test a layout for 15 seconds. In a previous version, I had the terminal SUI, purchasing, and building tour systems completed so now it’s a matter of doing the same for this version. I also need to come up with a way to address the single plot sites that can host huge buildings such as NPC hospitals, cantinas, and theaters – they’re so enormous that their site centers are quite far away from the road, meaning that any smaller building placed there would have a weird amount of empty space around it.

In any event folks, the “Hondo Housing System” is coming along, thanks to… the math I thought I would never use. 🙂