[0.12.x][0.12.5]Bob's Library mod

[bobingabout]

This mod adds a lot of new functions to the game. They are used by many of my mods, and can easilly be used by other mods too.

Latest: V0.12.5 - 26th June 2016
Dropbox Latest
Archive

Full documentation to follow. (I'll complete it another day.)

All functions are currently listed under bobmods.lib.function_name


bobmods.lib.item(item)
This function will create and return a completed item table, from an incomplete item table.
Requirements
{name, amount} or {name = name, optionals}

The optionals will be:
type =
This tag must list a valid item type if used. If not listed the type defaults to "item", but will perform a scan of all other known item types to see if it exists, and set it if it does.
amount =
This tag must list a quantity number. it defaults to 1 if not listed.
amount_min =
amount_max =
These 2 tags must be used as a pair, and list the minimum quantity and maximum quantity given. This is aimed for use as a result, not an ingredient.
probability =
This is another result only tag, and must list a floating point number between 0 and 1.
Examples:

Code: Select all

bobmods.lib.item{"iron-ore", 2}

This example will convert the listed item table to {type = "item", name = "iron-ore", amount = 2}

Code: Select all

bobmods.lib.item{name = "heavy-oil"}

This example will create the following table: {type = "fluid", name = "heavy-oil", amount = 1}

Code: Select all

bobmods.lib.item{name = "copper-ore", amount_min = 1, amount_max = 10, probability = 0.5}

This example is of a result type, and can be used as a mining result to be added to an ore resource. Assuming it was added to the iron ore results table using the apropriate ore manipulation function, mining iron ore would result in 1 to 10 items of copper ore per mining cycle 50% of the time(on top of iron ore if done correctly). The final table will be: {type = "item", name = "copper-ore", amount_min = 1, amount_max = 10, probability = 0.5}

bobmods.lib.get_item_type(item_name)
This function takes the name of any type of item, and returns its type.
the possible results are: "ammo", "armor", "capsule", "fluid", "gun", "mining-tool", "module", "tool" and of course "item".

Examples:

Code: Select all

bobmods.lib.get_item_type("iron-ore")

The function will return: "item"

Code: Select all

bobmods.lib.get_item_type("heavy-oil")

The function will return: "fluid"

Code: Select all

bobmods.lib.get_item_type("speed-module")

The function will return: "module"

Code: Select all

bobmods.lib.get_item_type("science-pack-1")

The function will return: "tool"
(Factorio version 0.12.0 changed the type from item to tool to allow the gradule usage of a science pack during research)

bobmods.lib.get_simple_item_type(item_name)
This function takes the name of any type of item, and returns its type. This is used by the bobmods.lib.item function.
the possible results are: "fluid" or "item".
This is basically the same function as above for use with recipe ingredients and recipe/mining results. They need to be either "item" or "fluid" as all other item types are a sub-type of "item".



Here is a breakdown of the ore based functions, and their table structures on what you need to do to make a new resource using my functions.
bobmods.lib.create_autoplace(data)
This function will return a table to be used on the autoplace = tag of a resource. it can actually be used on any entity to be placed in the world.
An example use would be:

Code: Select all

autoplace = bobmods.lib.create_autoplace{name = "lead-ore", size = 1.5, richness = 0.5, starting_area = true}

name will set which Autoplace control and Noise layer to be used (needs to be created elsewhere), In the above example, it will be named "lead-ore".
size sets how large of an ore field to create, 1 is similar to stone, 1.5 is similar to iron/copper etc, 2 starts be apear fairly often. Setting this too high will result in the entire map being covered by the resource.
richness sets how much ore exists in the resource placed on the map, 1 is about normal quantity. Sugested ranges from 0.1 to 10.

bobmods.lib.add_item_to_resource(resource, item)
This is the structure as of boblibrary 0.12.1.
Example:

Code: Select all

  bobmods.lib.add_item_to_resource("gem-ore", {name="diamond-ore", probability = bobmods.gems.DiamondRatio})

This takes 2 variables. resource is the name of the resource the item will be added to, and item is a table containing item information.
Valid tags on item include: type, name, probability, amount, amount_max and amount_min, just like a standard recipe table for an item. The added bonus of this function is that it will add in the type and amount tags if needed, defaults being type="item" and amount=1.
As of 0.12.1 the item table is fed through the bobmods.lib.item function, which will complete an incomplete table and set the correct item type, rather than defaulting to type="item" if not set.

bobmods.lib.create_ore_item(data)
This one is called by the "big" resource creation function, so is only needed if you want multiple items from a single resource.
Example:

Code: Select all

bobmods.lib.create_ore_item{name = "lead-ore", icon = "__bobores__/graphics/icons/lead-ore.png",
 subgroup = "bob-ores", stack_size = 200}

name and icon are required, subgroup and stack_size are option. the default for subgroup is "raw-resource" and the default stack size is 200.

bobmods.lib.create_ore_resource(inputs)
This is where it starts to get a little complicated, this function requires quite a large table to function.
bobmods.lib.create_ore_resource{
name = "lead-ore",
-- This line sets the resource internal name. it is required.
icon = "__bobores__/graphics/icons/lead-ore.png",
-- This line specifies the icon, it is required.
hardness = 0.7,
-- This line sets resource hardness, it is optional, default is 0.9
mining_time = 1.5,
-- This line sets the mining time, it is optional, default is 2
tint = {r = 0.5, g = 0.5, b = 0.5},
-- Sets the tint, aka, colour of the ore. each value scales from 0 to 1 to set the colour in RGB format. defaults to white.
map_color = {r=0.250, g=0.250, b=0.250},
-- Map colour, optional, but I'm not sure what the result is it you don't include it.
stage_mult = 10,
-- Sets the multiplier between the stages, 10 is a good figure. with a default value of 10 the final stage apears at 1280.
sprite =
{
sheet = 1,
-- there are 5 sheets to choose from, 1 being iron ore based, 2 being copper ore based, 3 being stone based, 4 being coal based, significantly lightened to be tintable, and 5 being oil style.
-- Additionally, you can set a filename= tag instead of a sheet tag inside the sprite table, to set a sprite sheet directly.
scale = 1,
-- sets the size scale.
width = 38,
-- image width per frame
height = 38,
-- image height per frame
frame_count = 4,
-- this is actually the different variations of each ore at a specific richness level.
variation_count = 8
-- this sets the number of richness levels.
},
--The sprite table is optional, sheet 1 will be used by default. Additional tags will default to those apropriate for a pre-defined sheet.
particle = "lead-ore-particle",
-- specifies the internal name for the particle to use, I think this is required, I havn't tested without.
category = "basic-solid",
-- Sets the mining catagory
minimum = 35,
-- Sets the infinite minimum amount
normal = 350,
-- Sets the normal infinite amount. at this level the ore has 100% yield
infinite = false,
-- sets if the ore is infinte or not.
collision_box = {{ -0.1, -0.1}, {0.1, 0.1}},
-- sets the resource collision box for tile placement
selection_box = {{ -0.5, -0.5}, {0.5, 0.5}},
-- sets the selection box when you point to the resource
disable_map_grid = false,
-- if set to true, the map colour will be a solid, rather than a grid
}


bobmods.lib.generate_ore_data_stage(inputs)
This uses the same table as above with additions. For best results you should create a table variable entry first, then pass the table varible to the function. The function may try to write back to it. This is called in my ores mod in the data loading stage.
Firstly, a change from the above function would be that with the particle line, it is now optional. if no line is defined a particle is automatically created and coloured using the tint line.
item = {create = true, subgroup = "bob-ores", stack_size = 200}
The item line as above lists all the acceptable variables. if create is set to true, the ore item will be generated as in the bobmods.lib.create_ore_item, using the same name and icon as used by the resource. This will automatically be added to the drop table for the resource with amount = 1 and probability = 1 set. If the create = true tag is present, the function will try to write back to this tag and to the items table listed below. If you want to use a different amount or probability you should create the item first using bobmods.lib.create_ore_item yourself, then add item table to the tag below.
items{}
This table lists an array of item tables as used by the bobmods.lib.add_item_to_resource function listed above. These are added to the resource's drop table.
autoplace =
{
create = true,
starting_area = true,
richness = 1.2,
size = 1
}
The above table can hold one of 2 different sets of data. if the create = true tag exists, it requiers the same information as bobmods.lib.create_autoplace. it does not need the name tag as that is passed in from the main table. if no additional tags are specified, it will use defaults. if the tag is missing completely, it will create it anyway, and assume defaults. This is not applied to the resource in this stage.
The alternate set of information you can supply to this tag is the already completed autoplace data as would be generated by the bobmods.lib.create_autoplace function. If the create = true tag is present, the function will try to write back to the input table.

bobmods.lib.generate_ore_updates_stage(inputs)
This function checks for 2 tags. You can pass through the entire data block as used in the previous function if you like.
The function will create an autoplace control and noise layer, then copy the contents of the autoplace tag onto the specified resource. this is called by my mod in the data-updates stage.
name = "lead-ore"
This tag should contain the name of the resource you wish to add autoplace controls to. if no resource is found with this name, the function will end.
autoplace =
this tag needs to contain the entire data to be used on a resources autoplace tag.

bobmods.lib.generate_ore(inputs)
This function calls bobmods.lib.generate_ore_data_stage then bobmods.lib.generate_ore_updates_stage. This uses the same data table as the mentioned functions to create the whole thing in one instruction. There is no real reason why you can't call the updates stage function in the data stage if you're sure you're going to use that ore in your mod.

A final example:

Code: Select all

lead_ore =
{
  name = "lead-ore",
  icon = "__bobores__/graphics/icons/lead-ore.png",
  hardness = 0.7,
  mining_time = 1.5,
  tint = {r = 0.5, g = 0.5, b = 0.5},
  map_color = {r=0.250, g=0.250, b=0.250},
  item =
  {
    create = true,
    subgroup = "bob-ores",
  },
  stage_mult = 10,
  sprite =
  {
    sheet = 1
  },
  autoplace = 
  {
    create = true,
    starting_area = true,
    richness = 1.2,
    size = 1
  }
}
bobmods.lib.generate_ore(lead_ore)

[Hovadko]

What does this mod do? Could you provide some simlified explanation please?

[Athmagor]

What does this mod do? Could you provide some simlified explanation please?

It is supposed to gather together all LUA functions that other mods use and it will become a base prerequisite for them.

The mod can be also used by other modders, as the functions are very useful and make modding scripts much more readable.

[bobingabout]

By itself it does nothing.

It contains code that would be repeated in several mods, to make modding easier, and the mods that use it smaller.

And often less buggy too. I've had several reports of compatabillity issues with my mods not playing nice with other mods, some of the code in here is designed to make them more friendly.

[Vin]

By itself it does nothing.It contains code that would be repeated in several mods, to make modding easier, and the mods that use it smaller.

Quoting this for emphasis, mostly on the repeated code bit. Obviously it's nice to have smaller, more efficient mods, but one of the biggest benefits for the end player is that mods that use the same code wind up being much more compatible. Using Minecraft as an example, the modding scene wouldn't be nearly what it is without Forge.

Obviously saving modder time and headache is also a huge benefit, but most end players don't think about that.

[Degraine]

Ho are these functions accessed by other mods? Do we have to require() them into data.lua?

[bobingabout]

Ho are these functions accessed by other mods? Do we have to require() them into data.lua?

They are available for other mods to use, yes. I recomend you make this mod a dependacy in info.json, and the functions will all be available without the need for a require.

[UberWaffe]

@bobingabout:
It would be helpful if the following function could be added to the library for recipe functions:

Code: Select all

function bobmods.lib.change_recipe_item_amount (recipe, item, newAmount)
  for i, ingredient in pairs(data.raw.recipe[recipe].ingredients) do
    if ingredient[1] == item or ingredient.name == item then
      ingredient.amount = newAmount
    end
  end
end

(Or something that does the same. Above code not yet tested.)

It saves having to use

Code: Select all

bobmods.lib.remove_recipe_item ("foo", "bar")
bobmods.lib.add_recipe_item ("foo", {"bar", 9999})

and makes the intention of the modifying code more clear.

Also, thanks for creating this library. Extremely helpful indeed.

[Airat9000]

0.12.15

[bobingabout]

0.12.15

Can you provide the complete mod's list please?

[Airat9000]

0.12.15

Can you provide the complete mod's list please?

files
https://yadi.sk/d/BsRYkndpkFyby

[bobingabout]

A list would have been sufficient.

The problem is that my electronics mod is not compatable with Yuoki Engines 1.7, (not sure why yet. (Seems to be a call to my library mod though))

I am not currently working on mods, due to job issues.

[IhanaMies]

How the function bobmods.lib.replace_recipe_item should be used?

If I use:
bobmods.lib.replace_recipe_item ("tank-3", "tungsten-carbide", "tungsten-carbide", 440)
amount won't change

or
bobmods.lib.replace_recipe_item ("tank-3", "tungsten-carbide", {"tungsten-carbide", 440})
brings error and game won't start

Instead I have to use:
bobmods.lib.remove_recipe_item ("tank-3", "tungsten-carbide")
bobmods.lib.add_recipe_item ("tank-3", {"tungsten-carbide", 440})

[bobingabout]

How the function bobmods.lib.replace_recipe_item should be used?

If I use:
bobmods.lib.replace_recipe_item ("tank-3", "tungsten-carbide", "tungsten-carbide", 440)
amount won't change

or
bobmods.lib.replace_recipe_item ("tank-3", "tungsten-carbide", {"tungsten-carbide", 440})
brings error and game won't start

Instead I have to use:
bobmods.lib.remove_recipe_item ("tank-3", "tungsten-carbide")
bobmods.lib.add_recipe_item ("tank-3", {"tungsten-carbide", 440})

bobmods.lib.replace_recipe_item is designed to replace one item in a recipe with the same amount of another item, EG, I use it to change Electronic Circuits into Basic Electronic Boards in my electronics mod.

If you want to change the amount, you can either use what you have done already (Remove than Add), or use bobmods.lib.add_recipe_item(recipe, item), in your example bobmods.lib.add_recipe_item("tank-3", {"tungsten-carbide", 400}) or bobmods.lib.add_recipe_item("tank-3", {name = "tungsten-carbide", amount = 400}), it will recognise both methods of defining an item.

If the item already exists, bobmods.lib.add_recipe_item will add the listed amount to the existing items listed amount.
Since the example recipe starts with 40 tungsten carbide, and we told it to add 400 tungsten carbide, it will result in 440, which is your desired quantity.

bobmods.lib.add_recipe_item should not be confused with bobmods.lib.add_new_recipe_item, the latter will only add the item if it is a new item, if it already exists, the command will be ignored. This version was added for instances where I have multiple mods trying to make the same changes, to prevent twice as many of the item being added if two mods were trying to add the same thing.

Make sense?

[Dynomyk3]

Cant download because its telling me the sites bandwidth limit was exceeded

[daniel34]

Cant download because its telling me the sites bandwidth limit was exceeded

Temporary solution:
https://www.dropbox.com/s/ooui2pq4y0fso ... 7.zip?dl=0

[LuziferSenpai]

Hey bob,

i found a small "bug".

If a tech has no prerequisites than that make an error!

Here is the fix:

Code: Select all

--Make this:
if not data.raw.technology[technology].prerequisites then
    	data.raw.technology[technology].prerequisites = {}
--after:
local addit = true

Than there is no error anymore!

Greetz,

Luzifer

[bobingabout]

Hey bob,

i found a small "bug".

If a tech has no prerequisites than that make an error!

Here is the fix:

Code: Select all

--Make this:
if not data.raw.technology[technology].prerequisites then
    	data.raw.technology[technology].prerequisites = {}
--after:
local addit = true

Than there is no error anymore!

Greetz,

Luzifer

I see it.

It will be fixed for the next release, whenever that may be.

Also noticed, now that I actually know the difference between pairs, and ipairs, how they work, and what they should be used for, that I should be using ipairs instead of pairs for these functions.

[Blu3wolf]

Hey bob,

i found a small "bug".

If a tech has no prerequisites than that make an error!

Here is the fix:

Code: Select all

--Make this:
if not data.raw.technology[technology].prerequisites then
    	data.raw.technology[technology].prerequisites = {}
--after:
local addit = true

Than there is no error anymore!

Greetz,

Luzifer

I see it.

It will be fixed for the next release, whenever that may be.

Also noticed, now that I actually know the difference between pairs, and ipairs, how they work, and what they should be used for, that I should be using ipairs instead of pairs for these functions.

Is there a functional difference within the context of Factorio?

[orzelek]

I think that I seen post from Rseding saying that we should only use pairs. Not sure where it was so won't link it directly.