Creating Placement Items

First of all, this builds on top of my previous blog update so you should read that now if you have yet to. This post will go a little more in-depth into what it takes to create an item that can be placed in the world.

Starting out lets say you are an amazing artist or have one on hand – like I do! Said artist has created an ingenious llama statue.

Now you want to place it into the game… but how do you do that? Inside of your item mod directory you need to create a content script so Crea knows about your statue. Here is what the script would look like.

name = 'Llama Statue'

#Render Component
render = Render('mods/base/item/llama_statue.png')
add(render)

#Item Component
item = Item()
item.stack = 999
item.delay = 200
add(item)

#Craft Component
craft = Craft('Home', 'Decoration', '') #Category, Subcategory, Surface
craft.add('mods/base/tile/stone.py', 50) #Materials needed
craft.quantity = 1 #Quantity made from a single craft
add(craft)

#Placement Component
placement = Placement()
placement.addAxis(PlacementAxis(AxisType.AXIS_FLOOR), Vector(5, 32))
add(placement)

I added in some comments for the crafting since I have not covered that before, but what we are really looking at is the placement component at the bottom. Items are composed off a list of possible axes that the item can be placed on.

The item can be placed on any axis but only one at a time. The types are floor, ceiling, left, right, backwall and wall. Backwall is the a tile in the wall layer. Wall is the combination of left and right. In addition to the axis type, each axis has a range, an area, and a list of supports.

The range of an axis defines where and how much support is needed to place the item down. This is the second parameter for PlacementAxis. In this case we have Vector(5, 32), which translates to start at pixel 5 on the bottom of the image (since it is floor) and go for 32 pixels. This will default to starting at 0 and using the entire axis length. The reason for this feature is to enable items to have a skinny base and only require support for the base and not the entire width of the item.

Area for an axis is the game’s physical representation of the item relative to upper left corner of the image. This area is used to reserve space for items in the world. This area defaults to the size of the image.

The last part of an axis is the list of support it can provide. It is defined very similarly to an axis with a support type and a range of where and how much support to provide. The type can be on any one of the four sides; top, bottom, left or right. Here is an example of a table placement with support on the top.

placement = Placement()
floorAxis = PlacementAxis(AxisType.AXIS_FLOOR)
floorAxis.addSupport(PlacementSupport(SupportType.SUPPORT_TOP, Vector(3, 57)))
placement.addAxis(floorAxis)
add(placement)

And now we have a llama standing on a table!

Here are a few cool features about the placement system.

• Item placement is on a per pixel – not a grid.
• Item placement is smart and provides some tolerance to moving to unavailable spaces.
• When you have a placeable item as your active item you will see a semi-transparent hint of where it will be placed.
• An item can have an animation component added to it with animations named to the different axes. The game will automagically use the correct animation when the item is placed.
• An axis can have any number of supports, which means that you can do something like a Menorah.

Overall this system is really flexible and provides an extreme amount of power to both modders and world construction. Currently its biggest limitation is that items cannot be placed inside of another item. This limits some items such as a bookcase and placing individual books in it. It is probably still possible – just have to be creative! If the demand is high in the future I may revisit this limitation but for now it is something I am willing to live with.

Feel free to ask any questions or give constructive feedback. This is my first attempt at writing a more in-depth guide to modding.