S2F - Basic LuA and Advancing Animation.

Start to Finish - Basic LuA and Advancing Animation.

Hello again, my second tutorial in the series.
We are going to now learn basic LuA and animations.
If you haven't seen my first tutorial on how to make pixel art and animate. Go there.
http://community.playstarbound.com/...pixel-art-and-putting-it-into-the-game.57153/

INDEX

1. Part 1: On and off Scripting
2. Part 2: Part based Animation
3. Part 3: We shall see.

Part 1: On and Off scripting.

Overview:
In Part one of the tutorial. We will see how to make an object turn its animation on and off when interacting with it.

Before you start the tutorial you would have to at least read part 2 of the previous tutorial, which covers

• Creating a recipe
• Modifying an object file.
• Creating a Mod Info File.
• Modifying player config file.

Chapter 1: Setting it up.
Ok lets get started.
First thing lets open your starbound folder.

Code:

C:\Program Files (x86)\Steam\steamapps\common\Starbound

Go to your mods folder, and make sure its empty. Just backup any mods you have installed.
[Not covering how to merge mods - because of pending update]

Now create a new folder inside mods folder and lets name it sdish.

Now we want to create a few folders inside sdish

Code:

Starbound\mods\sdish\objects\generic

Code:

Starbound\mods\sdish\objects\wired

Code:

Starbound\mods\sdish\recipes

Now go to

Code:

C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\objects\wired\ironbeacon

and copy

• ironbeacon.animation
• ironbeacon.lua

to your corresponding mod folder.
Rename the files

• sdish.animation
• sdish.lua

Now go to

Code:

C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\objects\boss

and copy

• ironbeacon.object
• ironbeacon.png
• ironbeaconicon.png

Place it in the corresponding objects folder. [boss folder not required]
Rename the files

• sdish.object
• sdish.png
• sdishicon.png

Finally go to

copy the ironbeacon.reciepe and place it in the associated mod folder.
In total you would have copied 6 items.

So our directory structure would look like







Keep note at the path bar on top.

Chapter 2: Code Clean up

DISCLAIMER - If you know how to re-associate all the files to sdish. Feel free to skip this chapter. Otherwise read on

Now we have all our files and renamed them. We are going to need to change the code to sdish for all of them.
lets open up sdish.object first.

Code:

{
  "objectName" : "sdish",
  "rarity" : "Common",
  "objectType" : "wire",
  "description" : "A distress beacon. Who knows who might hear it?",
  "shortdescription" : "Sdish",
  "race" : "generic",
  "category" : "decoration",
  "printable" : "false",
  "apexDescription" : "A distress beacon. I hope the person who left it is okay.",
  "avianDescription" : "A distress beacon. Someone must be in trouble.",
  "floranDescription" : "Floran help as well as hunt. Sssometimes.",
  "glitchDescription" : "Analysis. This distress beacon is transmitting at a number of frequencies.",
  "humanDescription" : "This beacon's sending out a distres call.",
  "hylotlDescription" : "Someone needs help. Protecting the weak is a worthwhile pursuit.",

  "inventoryIcon" : "sdishicon.png",
  "orientations" : [
    {
      "dualImage" : "sdish.png:<color>.<frame>",

      "imagePosition" : [-16, 0],
      "frames" : 12,
      "animationCycle" : 2,

      "spaceScan" : 0.1,
      "anchors" : [ "bottom" ]

    }
  ],

  "animation" : "/objects/wired/sdish.animation",
  "animationParts" : {
    "beacon" : "sdish.png"
  },
  "animationPosition" : [-16, 0],

  "scripts" : [ "/objects/wired/sdish.lua" ],
  "scriptDelta" : 5

}

Any where it says ironbeacon replace it with sdish. Make sure the name matches the files you made accordingly.
A quick and easy way to do it is to press Control + F [ in notepad++ - if you don't have read my first tutorial]

• you will see a replace tab.
• type in ironbeacon
• choose replace as sdish
• hit replace all

Now double check to make sure its been all changed. Short description will need to be changed manually since there was a space. It should match the code provided above.

Don't worry about the script location, since we made our directory architecture in mods too match we are safe.
Also do not worry about the beacon in parts. Reason for it is described below.

== Extra Lesson ==
One new piece of code is there. Which wasn't covered in the previous tutorial
[
CODE] "animationParts" : {
"beacon" : "sdish.png"
},[/CODE]

Animation parts
Basically it is defining part of the object which is named in the associated frames file.
In our case it is default. Which will associate with anyone name. But, if our png had multiple different images, each assigning a different part to our object. We would have to name each part accordingly and our frames file will handle the associations.

For sake of example we will look at

Code:

  "animation" : "turret.animation",
  "animationParts" : {
    "gun" : "turret.png",
    "bracket" : "turret.png",
    "beam" : "beam.png"
  },

On first glance you will see the gun has 2 states and 2 parts shown.

Parts are

• Bracket [called neck in image, bracket in code. Artist and programmer had disagreements ]
• Gun

States are

• Idle
• Attack

the frame code it is

Code:

{
  "frameGrid" : {
    "size" : [48, 23],
    "dimensions" : [4, 2],

    "names" : [
      [ "idle", null, null, "bracket" ],
      [ "attack.1", "attack.2", "attack.3", "attack.4" ]
    ]
  }
}

Size
Syntax is [Single frame width in pixels, single frame height in pixels]

Dimension
Now both numbers are used. A quick reminder [horizontal frames, vertical frames] is the syntax.

Names
names wasn't covered before, essentially here you are now designating the name of each frame

• Null - represents frames to be ignored
• Idle and bracket - are single frames non animated
• Attack.# - represents to play this frame in this order.

the word attack can of course be changed to anything.
Syntax being

Code:

name.#

Naming is important since we will be calling these names from LuA.
We will cover more of this particular topic next Part. I just covered this so you have an idea about what is going on.
=== END LESSON ===


sdish.frames you don't need to touch.

Lets open sdish.recipe now.

Code:

{
  "input" : [
    { "item" : "darkwoodmaterial", "count" : 1 }
  ],
  "output" : {
    "item" : "sdish",
    "count" : 1
  },
  "groups" : [ "plain", "all", "other" ]
}

We will want to change item output to sdish. Also you may have noticed I changed all the inputs to darkwood. I have done this for testing purposes. Since wood is easy to find and easy to test with. Feel free to follow suite or set your own. Of course you can change it later after testing.

Some of you may have also noticed I changed the groups of crafting. Also for testing purposes. I wanted to be able to craft it anywhere to quickly test. Now that your recipe is done.
[ Disclaimer - All this is thoroughly explained in the previous tutorial. Link found on top to this page. ]

Now finally we need to deal with sdish.animation.

Code:

{
  "animatedParts" : {
    "stateTypes" : {
      "sdishState" : {
        "default" : "idle",
        "states" : {
          "idle" : {
            "frames" : 1,
            "cycle" : 0.15
          },
          "active" : {
            "frames" : 12,
            "cycle" : 0.7,
            "mode" : "loop"
          }
        }
      }
    },

    "parts" : {
      "beacon" : {
        "properties" : {
          "centered" : false
        },

        "partStates" : {
          "sdishState" : {
            "idle" : {
              "properties" : {
                "image" : "<partImage>:default.default"
              }
            },

            "active" : {
              "properties" : {
                "image" : "<partImage>:default.<frame>"
              }
            }
          }
        }
      }
    }
  }
}

We will want to change all "beaconStates" to "sdishStates"
leave the part beacon as is - as mentioned before. It is being referenced by the object file.
If you changed it on your own accord, it will have to be changed to what ever name you gave it in the objects file.

Now the animation piece of the code looks very complex. But can be break it down easily.
If you are using Notepad++ as recommended, you can easily break down the hierarchy by following the curly brackets.

For those of you are lost. Go back to basic math where you had calculations in parentheses. Inside calculations are done first as opposed to out side.

In programming its almost along the same lines. What is inside the top most bracket is considered part of the parent function.
So in this case the hierarchy is

1. Animated Parts
   1. stateTypes
      1. sdishState
         1. default
         2. states
            1. idle
            2. active
   2. parts
      1. beacon
      2. partStates
         1. sdishState
            1. idle
            2. active

One thing to keep in mind each piece we define is only associated within the hierarchy it is in.

Animated parts
Required.

Statetypes
First we are defining which one is the default state from the states we define later.

States
We describe the states
How many frames it has - which is defined in the frames file
Cycle defines how fast to cycle through it.

Mode
Variations of modes will be listed.
But how the animation runs. Loop would essentially be once it finishes the animation it starts from the beginning.

Properties [under beacon parts. ]
various properties are

• offset : [x, y]
• rotationGroup : "x", - not sure [?]
• centered : false or true
• zLevel : 0, 1, 2 [background middle foreground layer [?]]

partStates
Defined by the object file and described by the statetypes from the above section.
In our case we only had 1 state. sdishState.

But if you look at the turret.animation

Code:

 "movement" : {
        "priority" : 0,
        "default" : "idle",

        "states" : {
          "idle" : {
            "frames" : 1
          },
          "attack" : {
            "frames" : 4,
            "cycle" : 0.25,
            "mode" : "loop"
          }
        }
      },
      "beam" : {
        "default" : "invisible",

        "states" : {
          "invisible" : { "frames" : 1 },
          "visible" : { "frames" : 1 }
        }
      }

It has 3.

• Movement
• Attack
• Beam

Now back to our Sdishstate.
We now define what are the states.
We have Idle and Attack set up and now another properties.

Properties [under states]
Here we are defining the image and animation.

Code:

"image" : "<partImage>:default.default"

Code:

<part image>

is referencing what image to use in you objects file.

Code:

:default

is referencing which name in the Frames file.
In our case we only have one name.

Lets go back to our turret example from above. you would have remembered 3 names.

• bracket
• idle
• attack

now finally

Code:

.default

only required if its an animated part otherwise not needed. No animation would be idle state of turret as previously mentioned.
If there is only a single part in that image. .default is fine for the stream
if the image contains multiple images as our turret used <frame> as opposed to .default
this will play all the frames accordingly in order.

Now we are done with the explanations.
Final code should be same as the one provided earlier.
So lets move onto the LuA shall we?

Chapter 3: Getting the feet wet.
Ok now open sdish.lua and delete everything inside. Explanations for it will be another time, in a further tutorial.
Scary isn't it staring at a blank page for the first time.
Don't worry

Now here is the code we will be working with.

Code:

function init(args)
  entity.setInteractive(true)
  end

function onInteraction(args)
        if entity.animationState("sdishState") == "idle" then
                entity.setAnimationState("sdishState","active")
        else
                entity.setAnimationState("sdishState","idle")
        end
end

Very simple, no?

LUA code here is based on various functions. Each function defines what is going to happen in what condition.

In our first line.

Code:

function init(args)
  entity.setInteractive(true)
  end

int(args)
We are saying on initialization what do we want to happen.

entity.setInteractive(true)
We are stating the object on intialization what will happen - so in our case true. It will be interactive on initalization.

Now we end it.
Because the function is about what happens when it is initalized. We will now describe what happens when its interacted with.

Code:

function onInteraction(args)
        if entity.animationState("sdishState") == "idle" then
                entity.setAnimationState("sdishState","active")
        else
                entity.setAnimationState("sdishState","idle")
        end
end

function onInteraction(args)
Here we are defining what happens when we interact with the entity.

if entity.animationState("sdishState") == "idle" then
We are refrencing the state in Lua we did in animation.

So we setup the value "idle"
If you remember default state is Idle as referenced by the animation.

then
we are now stating what happens if its in idle by the next line.

entity.setAnimationState("sdishState","active")
we are changing the value of sdish state to active

else
entity.setAnimationState("sdishState","idle")

If sdishState was not idle to begin with on interaction then we are setting the state to idle
We are finished!
of course end which closes else functions

======
By now you should have a basic idea of how to make a basic playerconfig file and modinfo file which associates with items.
If you don't know how please follow Part 2 of the first tutorial.
http://community.playstarbound.com/...pixel-art-and-putting-it-into-the-game.57153/

For those who wish can download the sample mod here. If you have any issues, you can compare what you did wrong.
https://www.mediafire.com/download/sjmxfs1z4zqqjgi/mods3.rar

=======
Another tutorial done. 2 More parts will come based on this. Stay tuned.
If you liked it, have any questions, comments, found a mistake. Feel free to Reply. Don't forget to share to others if found useful.
Honorable mention to Pocico for assistance in LuA.

 

Part 2 Reserved

 

Part 3 Reserved

 

Glad you liked it - you will need to update your code to follow the tutorial in Angry Koala.

Notice:
LuA reference code has changed in Angry Koala
The reference Object has now become Entity.

The tutorial has been updated accordingly.
Will be updating first tutorial with new merge tutorial for config files tonight

 

Thx - I forgot about that for a long time
fixed