Deal with FrameBuffers as render targets and textures. Color and Depth buffers need to be allocated and managed.

So we need to be baked within an oven so we will talk about the return from the bake function rather than the module function.

local framebuffers=oven.rebake("wetgenes.gamecake.framebuffers")

local fbo=framebuffers.create(256,256,0)	-- a 256x256 texture only
local fbo=framebuffers.create(256,256,-1)	-- a 256x256 depth only
local fbo=framebuffers.create(256,256,1)	-- a 256x256 texture and depth
local fbo=framebuffers.create()				-- 0x0 and we will resize later

local fbo=framebuffers.dirty()
local fbo=framebuffers.dirty(x,y)
local fbo=framebuffers.dirty(x,y,framebuffers.NEED_TEXTURE_AND_DEPTH)
local fbo=framebuffers.dirty(0,0,0,{
    depth_format={gl.DEPTH_COMPONENT32F,gl.DEPTH_COMPONENT,gl.FLOAT},
    texture_format={gl.RGBA,gl.RGBA,gl.UNSIGNED_BYTE},
    TEXTURE_MIN_FILTER=gl.LINEAR,
    TEXTURE_MAG_FILTER=gl.LINEAR,
    TEXTURE_WRAP_S=gl.CLAMP_TO_EDGE,
    TEXTURE_WRAP_T=gl.CLAMP_TO_EDGE,
}) -- note this table will be returned as the fbo

Create a new framebuffer object and optionally provide an inital size and depth. The depth can use -1,0,1 or the following verbose flags framebuffers.NEED_DEPTH,framebuffers.NEED_TEXTURE or framebuffers.NEED_TEXTURE_AND_DEPTH to request a depth buffer(1,-1) or not(0).

Finally you can pass in a table to be returned as the fbo that contains defaults or set defaults in the fbo that is returned.

fbo.depth_format={gl.DEPTH_COMPONENT32F,gl.DEPTH_COMPONENT,gl.FLOAT}

Can be used to control exactly how a depth buffer is allocated with gl.TexImage2D when you care about that sort of thing, IE hardware issues.

fbo.texture_format={gl.RGBA,gl.RGBA,gl.UNSIGNED_BYTE}

Can be used to control exactly how a texture buffer is allocated with gl.TexImage2D when you care about that sort of thing, IE hardware issues.

fbo.TEXTURE_MIN_FILTER=gl.LINEAR
fbo.TEXTURE_MAG_FILTER=gl.LINEAR
fbo.TEXTURE_WRAP_S=gl.CLAMP_TO_EDGE
fbo.TEXTURE_WRAP_T=gl.CLAMP_TO_EDGE

These can be used to control default TexParameters in the fbo.

fbo.no_uptwopow=true

By deafult we will use power of 2 sizes for the fbo that fit the requested size. This disables that and doing so will of course cause problems with some hardware. Generally if you avoid mipmaps it probably wont be a problem.

See #lua.wetgenes.gamecake.framebuffers.fbo for all the functions you can call on the fbo returned.

framebuffers.dirty()

Mark all framebuffer objects as dirty by setting fbo.dirty to be true. We do not do anything with this flag but it is used in external code and this is a useful helper function to set the flag.

fbo:bind_depth()

BindTexture the depth texture part of this fbo.

If there is no texture we will bind 0.

fbo:bind_depth_snapshot()

BindTexture the depth snapshot texture part of this fbo.

If there is no snapshot texture we will bind 0.

fbo:bind_depth()

BindFramebuffer the framebuffer of this fbo.

If there is no framebuffer we will bind 0.

fbo:bind_texture()

BindTexture the rgba texture part of this fbo.

If there is no texture we will bind 0.

fbo:bind_texture_snapshot()

BindTexture the rgba snapshot texture part of this fbo.

If there is no snapshot texture we will bind 0.

fbo:check()

Check and allocatie if missing and needed (eg depth texture may not be needed) all our openGL buffers.

fbo:clean()

Free all the opengl buffers.

fbo:download()
fbo:download(w,h,x,y)

Read back color data from a framebuffer and return it in an RGBA PREMULT grd object (which is probably what it is).

If a width,height is given then we will read the given pixels only from the x,y location.

fbo:free_depth()

Free the depth texture only, is safe to call if there is no depth buffer.

fbo:free_frame()

Free the frame buffer only, is safe to call if there is no frame buffer.

fbo:free_snapshot()

Free the snapshot buffers, fbo.texture_snapshot and fbo.depth_snapshot if they exist.

fbo:free_texture()

Free the rgba texture only, is safe to call if there is no rgba buffer.

fbo:mipmap()

Build mipmaps for all existing texture buffers.

fbo:mipmap_depth()

Build mipmaps for our depth buffer if it exists and set TEXTURE_MIN_FILTER to LINEAR_MIPMAP_LINEAR so it will be used.

It is possible this may fail (hardware issues) and the TEXTURE_MIN_FILTER be reset to gl.NEAREST along with a flag to stop us even trying in the future,

fbo:mipmap_texture()

Build mipmaps for our texture buffer if it exists and set TEXTURE_MIN_FILTER to LINEAR_MIPMAP_LINEAR so it will be used.

fbo:pingpong(fbout,shadername,callback)
framebuffers.pingpong({fbin1,fbin2},fbout,shadername,callback)

Render from one or more fbos into another using a fullscreen shader.

Sometime you need to repeatedly copy a texture back and though applying a shader, this is the function for you.

The textures will be bound to tex1,tex2,tex3,etc and the uvs supplied in a_texcoord with a_vertex being set to screen coords so can be used as is.

fbo:render_start()

Start rendering into this fbo.

Push old matrix and set the matrix mode to MODELVIEW

Set fbo.view and reset the gl state.

fbo:render_stop()

Stop rendering into this fbo and restore the last fbo so these calls can be nested.

Restore the old view and old gl state.

Pop old matrix and set the matrix mode to MODELVIEW

fbo:resize(w,h,d)

Change the size of our buffers, which probably means free and then reallocate them.

The w,h,d use the same rules as framebuffer.create

fbo:snapshot()

Take a current snapshot copy of the texture and depth if they exist, store them in fbo.texture_snapshot and fbo.depth_snapshot for later binding.

framebuffers.start()

Called as part of the android life cycle, since we auto reallocate this does not actually have to do anything. But may do a forced resize in the future if that turns out to be more hardware compatible.

framebuffers.stop()

Called as part of the android life cycle, we go through and call fbo.clean on each fbo to free the opengl resources.

tag_value = chat:get_tag(tag_name)

The same as chats:get_tag but the subject of this chat is the default root.

output = chat:replace_tags(input)

The same as chats:replace_tags but the subject of this chat is the default root.

tag_value = chat:set_tag(tag_name,tag_value)

The same as chats:set_tag but the subject of this chat is the default root.

chat:set_tags(tags)

Set all the values in the given table of {tag_name=tag_value} pairs.

chat:set_topic(topic_name)

Set the current topic for this chat object, information about this topic and its gotos are built from and stored in this chat object.

chat.topic_name

Will be set to the given topic name.

We merge all gotos found in this topic and all topic parents by iterating over the dotnames. We only use add each topic once and each topic may have a bit of logic that decides if it should be displayed.

<topic_name?logic_test

So this would goto the topic_name if the logic_test passes. The logic test is written simmilar to a url query after the question mark comes a number of tests that are then & or | together in left to right order (no operator precedence).

<topic_name?count<10&seen==false

So this would display the goto option if count is less than 10 and seen is set to false. These variables we are testing are tag_names and default to the current subject chat but could reference other subjects by explicitly including a root.

Available logic tests are

name==value
name=value

True if the tag is set to this value.

name!=value

True if the tag is not set to this value.

name<value

True if the tag is less than this value (numeric test).

name>value

True if the tag is more than this value (numeric test).

name<=value

True if the tag is less than or equal to this value (numeric test).

name>=value

True if the tag is more than or equal to this value (numeric test).

All of these tests can be preceded by a ! to negate them so

name!=vale
!name==value

Are both a test for inequality.

Multiple tests can be joined together by & (and) or | (or) this logic will be applied to a running total moving from left to right as the values are evaluated with the final value deciding if this goto will be displayed.

chats.changes(chat,change,...)

chats.changes(chat,"subject")
chats.changes(chat,"topic",topic)
chats.changes(chat,"goto",goto)
chats.changes(chat,"tag",tag_name,tag_value)

This is a callback hook, replace to be notified of changes and possibly alter then, by default we print debuging information. Replace this function with an empty function to prevent this eg

chats.changes=function()end

chat = chats:get_subject(subject_name)
chat = chats:get_subject()

Get the chat for the given subject or the chat for the last subject selected with set_subject if no subject_name is given.

tag_value = chats:get_tag(tag_name,subject_name)

Get the tag_value for the given tag_name which can either be "tag_root/tag_name" or "tag_name". The subject_name is the default root to use if no tag_root is given in the tag_name.

output = chats:replace_tags(input,subject_name)

Tags in the input text can be wrapped in {tag_name} and will be replaced with the appropriate tag_value. This is done recursively so tag_values can contain references to other tags. If a tag does not exist then it will not expand and {tag_name} will remain in the output text.

Again if any tag name does not contain an explicit root then subject_name will be used as the default chat subject.

chat = chats:set_subject(subject_name)

Set the current subject for this chats object, this subject becomes the chat that you will get if you call get_subject with no arguments.

tag_value = chats:set_tag(tag_name,tag_value,subject_name)

Alter the value of the given tag_name. If the value string begins with a "+" or a "-" Then the values will be treated as numbers and added or subtracted from the current value. This allows for simple incremental flag values.

Again if the tag name does not contain an explicit root then subject_name will be used as the default chat subject.

for part_name in chatdown.dotnames(full_name) do
    print(part_name)
end

Iterate all dotnames so if given "aa.bb.cc" we would iterate through "aa.bb.cc" , "aa.bb" and "aa". This is used to inherit data using just a naming convention.

rawsubjects = chatdown.parse(text)

Parse text from flat text chatdown format into heirachical chat data, which we refer to as rawsubjects, something that can be output easily as json.

This gives us a readonly rawsubjects structure that can be used to control what text is displayed during a chat session.

This is intended to be descriptive and logic less, any real logic should be added using a real language that operates on this rawsubjects and gets triggered by the names used. EG, filter out gotos unless certain complicated conditions are met or change topics to redirect to an alternative.

A self documented example of chatdown formated text can be found in lua.wetgenes.gamecake.fun.chatdown.text

chats = chatdown.setup_chats(chat_text,changes)

parse and initialise state data for every subjects chunk creating a global chats with a chat object for each subject.

chat = chatdown.setup_chat(chats,subject_name)

Setup the initial chat state for a subject. This is called automatically by chatdown.setup and probably should not be used elsewhere.

Here is some example chatdown formatted text full of useful information, it it is intended to be a self documented example.

- This is a single line comment
-- This is the start of a multi-line comment

All lines are now comment lines until we see a line that begins with a 
control character leading white space is ignored. If for some reason 
you need to start a text line with a special character then it can be 
escaped by preceding it with a #

What follows is a list of these characters and a brief description 
about the parser state they switch to.

    1. - (text to ignore)
    
        A single line comment that does not change parser state and 
        only this line will be ignored so it can be inserted inside 
        other chunks without losing our place.

    2. -- (text to ignore)
    
        Begin a comment chunk, this line and all lines that follow this 
        line will be considered comments and ignored until we switch to 
        a new parser state.

    3. #subject_name

        Begin a new subject chunk, all future topic,goto or tag chunks will 
        belong to this subject.
        
        The text that follows this until the next chunk is the long 
        description intended for when you examine the character.
        
        Although it makes sense for a subject chunk to belong to one 
        character it could also a group conversation with tags being 
        set to change the current talker as the conversation flows.
        
        subject names have simple cascading inheritance according to their 
        name with each level separated by a dot. A chunk named a.b.c 
        will inherit data from any chunks defined for a.b and a in that 
        order of priority.

    4. >topic_name
    
        Begin a topic chunk, all future goto or tag chunks will belong 
        to this topic, the lines that follow are how the character 
        responds when questioned about this topic followed by one or 
        more gotos as possible responses that will lead you onto 
        another topic.
        
        Topics can be broken into parts, to create a pause, by using an 
        unnamed goto followed by an unnamed topic which will both 
        automatically be given the same generated name and hence linked 
        together.
        
    5. <goto_topic_name
    
        Begin a goto chunk, all future tag chunks will belong to this 
        goto, this is probably best thought of as a question that will 
        get a reply from the character. This is a choice made by the 
        player that causes a logical jump to another topic.
        
        Essentially this means GOTO another topic and there can be 
        multiple GOTO options associated with each topic which the 
        reader is expected to choose between.
        
    6. =set_tag_name to this value
    
        If there is any text on the rest of this line then it will be 
        assigned to the tag without changing the current parse state so 
        it can be used in the middle of another chunk without losing 
        our place.
        
        This single line tag assignment is usually all you need. 
        Alternatively, if there is no text on the rest of this first 
        line, only white space, then the parse state will change and 
        text on all following lines will be assigned to the named tag.
        
        This assignment can happen at various places, for instance if 
        it is part of the subject then it will be the starting 
        value for a tag but if it is linked to a topic or goto then the 
        value will be a change as the conversation happens. In all 
        cases the tags are set in a single batch as the state changes 
        so the placement and order makes no difference.
        
        Tags can be used inside text chunks or even GOTO labels by 
        tightly wrapping with {} eg {name} would be replaced with the 
        value of name. Tags from other subjects can be referenced by 
        prefixing the tag name with the subject name followed by a forward 
        slash like so {subject/tag}
                

The hierarchy of these chunks can be expressed by indentation as all 
white space is ignored and combined into a single space. Each SUBJECT will 
have multiple TOPICs associated with it and each TOPIC will have 
multiple GOTOs as options to jump between TOPICs. TAGs can be 
associated with any of these 3 levels and will be evaluated as the 
conversation flows through these points.

So the chunk hierarchy expressed using indentation to denote children 
of.

    SUBJECT
        TAG
        GOTO
            TAG
        TOPIC
            TAG
            GOTO
                TAG

The GOTO chunks in the root SUBJECT chunk are used as prototypes so if a 
GOTO is used in multiple topics its text can be placed within a GOTO 
inside the main SUBJECT chunk rather than repeated constantly. This will 
then be inherited by a GOTO with no text. An alternative to this 
shorthand is to assign an oft-used piece of text to a tag and reference 
that in each topic instead.

SUBJECTs and TOPICs also have simple inheritance based on their names this 
enables the building of a prototype which is later expanded. Each 
inheritance level is separated by a dot so aa.bb.cc will inherit from 
aa.bb and aa with the data in the longer names having precedence. This 
inheritance is additive only so for instance a TAG can not be unset and 
would have to be changed to another value by aa.bb.cc if it existed in 
aa.bb or aa.

In practise this means
<br/>
<br/>

cells = require("wetgenes.gamecake.fun.yarn.cells").create(items)

This module contains only one function which can be used to create an cells instance and the rest of this documentation concerns the return from this create function, not the module itself.

items = require("wetgenes.gamecake.fun.yarn.items").create()

This module contains only one function which can be used to create an items instance and the rest of this documentation concerns the return from this create function, not the module itself.

items.cells

We automatically create a cells object bound to this set of items, this cells object should be used to define all your custom game cells.

item = items.create()
item = items.create({})
item = items.create({},metatable)

Create a single item, optionally pass in a base item table that will be turned into a proper item (using setmetatable to add methods). This should always be a new table and will also be returned. If no metatable is provided then items.metatable will be used.

items.pages

We automatically create a pages object bound to this set of items, this pages object should be used to define all your custom game pages.

This can be considered a level and you may need multiple pages which are moved in and out of items.pages

item = items.destroy(item)
item = item:destroy()

Destroy an item, remove it from the master table dump so it will be garbage collected.

child_item = item:find(keyname)

Get the first child item that has a [keyname] value in it. All child items are searched, but this is not recursive.

returns nil if no child item is found.

big_item = item:get_big()

Get the first big item from this container, returns nil if we do not contain a big item.

item = item:insert(parent)

Insert this item into the given parent. Item will automatically be removed from its current parent. If the item is_big then it will be inserted into the front of the list otherwise it will go at the end. This is to help with finding big items, since there should only be one per container we only have to check the first child.

for name,tail in items.iterate_dotnames(names) do ... end

Iterator over a names string, start with the full string and cut off the tail on each iteration. This is used for simple inheritance merging of named prefabs and rules or anything else.

Second return value is the tail of the string or the string if not tail.

for example the following input string

"one.two.three.four"

would get you the following iteration loops, one line per loop

"one.two.three.four" , "four"
"one.two.three"      , "three"
"one.two"            , "two"
"one"                , "one"

for it in item:iterate_parents() do
    ...
end

Iterate over the parent chain going upwards. The first iteration is the parent of this object and so on.

items.metatable

Expose the item metatable so more methods can easily be added.

items.prefabs

We automatically create a prefabs object bound to this set of items, this prefabs object should be used to define all your custom game prefabs.

item = item:remove()

Remove this item from its parents table or do nothing if the item does not have a parent.

items.rules

We automatically create a rules object bound to this set of items, this rules object should be used to define all your custom game rules.

pages = require("wetgenes.gamecake.fun.yarn.pages").create(items)

This module contains only one function which can be used to create an pages instance and the rest of this documentation concerns the return from this create function, not the module itself.

prefabs = require("wetgenes.gamecake.fun.yarn.prefabs").create(items)

This module contains only one function which can be used to create an prefabs instance and the rest of this documentation concerns the return from this create function, not the module itself.

prefab = prefabs:get(name)
prefab = prefabs:get(name,prefab)

Build and return a table with all prefab values inherited from all its parents. Optionally pass in a prefab to override values and also have it returned.

If name doesn't exist at any level and a table is not passed in then nil will be returned.

Names are hierarchical, separated by dots, see items.iterate_dotnames

rules = require("wetgenes.gamecake.fun.yarn.rules").create(items)

This module contains only one function which can be used to create an rules instance and the rest of this documentation concerns the return from this create function, not the module itself.

item = rules.apply(item,method,...)

item.rules must be a list of rule names and the order in which they should be applied to this item.

Call the given method in each rule with the item and the remaining arguments.

If the method returns a value then no more methods will be applied even if more rules are listed.

We always return the passed in item so that calls can be chained.

item = item:apply(method,...)

This function is inserted into the items.metatable so it can be called directly from an item.

yes = rules.can(item,method)

Returns true if any rule in this item has the given method.

yes = item:can(method)

This function is inserted into the items.metatable so it can be called directly from an item.

rule = rules.set(rule)

Set this base rule into the name space using rule.name which must be a string.

Multiple rules can be applied to an item and each rule will be applied in the order listed.

A rule is a table of named functions that can be applied to an item.

rule.setup(item)

Must setup the item so that it is safe to call the other rules on it.

rule.clean(item)

Should cleanup anything that needs cleaning.

rule.tick(item)

Should perform a single time tick update on the item.

oven=require("wetgenes.gamecake.oven").bake(opts)

The oven module must be baked so only exposes a bake function.

All the other functions are returned from within the bake function.

possible ENV settings

gamecake_tongue=english
gamecake_flavour=sdl

oven=wetgenes.gamecake.oven.bake(opts)

Bake creates an instance of a lua module bound to a state. Here we are creating the main state that other modules will then bind to.

We call each state an OVEN to fit into the gamecake naming scheme then we bake a module in this oven to bind them to the common state.

Think of it as a sub version of require, so require gets the global pointer for a module and bake is used to get the a module bound to an oven.

By using this bound state we reduce the verbosity of connecting modules and sharing state between them.

oven=require("wetgenes.gamecake.toaster").bake(opts)

A cut down oven without opengl or even file access intended to be used in a sub process or task.

oven=wetgenes.gamecake.toaster.bake(opts)

Bake creates an instance of a lua module bound to an oven state. Here we are creating the main state that other modules will then bind to.

Modules are then bound together using rebake...

b=oven.rebake(nameb)
c=oven.rebake(namec)

All of these will be connected by the same oven and circular dependencies should work with the caveat that just because you have the table for a baked module does not mean that it has all been filled in yet.

ticks=require("wetgenes.gamecake.toaster").newticks(rate,jump)

create a ticks time controller for updates.

rate is time between steps , jump is how far behind we should get before giving up ( eg callback takes longer than rate allows ) these values are in seconds and default to 1/60 and 1 respectively.

Then we perform one or more update steps like so

ticks.step( callback ) -- callback may be called zero or more times

After that we should wait a bit (maybe draw a frame) and then call again.

local widgets=oven.rebake("wetgenes.gamecake.widgets")

A collection of widgets, rendered using gles2 code and controlled using the mouse, keyboard or a joystick. EG click fire and move left/right to adjust a slider value.

Widgets must be created and bound to an oven, using the oven.rebake function.

This has undergone a number of rewrites as we try to simplify the widget creation and layout process. Eventually we ended up with a fixed size system of widget placement so every widget must have a known size in advance, however we allow scaling to occur so for instance building a 256x256 widget does not mean that it has to be displayed at 256x256 it just means it will be square.

The basic layout just lets you place these widgets in other widgets as left to right lines. So as long as you get your sizes right you can easily place things just using a list and without keeping track of the current position.

Other layout options are available, such as absolute positioning for full control and we have simple custom skin versions of the buttons as well rather than the built in skins.

All value data is handled by data structures that contain ranges and resolutions for data allowing the same data to be bound to multiple display widgets. For instance the same data can be linked to the position of a slider as well as the content of a text display. I think the kids call this sort of thing an MVC pattern but that's a terribly dull name.

Swanky paint is probably the most advanced used of the widgets so far but I suspect we will be making a simple text editor in the near future. Designed for advanced in game tweaking of text files.

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local widget=master:add{class="button",...}

A button for pressing and such.

see lua.wetgenes.gamecake.widgets.meta.setup for generic options

As a button we always need to be solid so this is forced to true.

Also cursor will be set to "hand" if it is not already set so you can tell it is a button when you hover over it.

this function will also call lua.wetgenes.gamecake.widgets.meta.update

If we have a data assigned to this button then make sure that the displayed text is up to date. We should really hook into the data so any change there is copied here instead?

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local widget=master:add{class="center",...}

A layout class for very centered children.

this function will also call lua.wetgenes.gamecake.widgets.meta.layout

Place any children in the center of this widget. Multiple children will overlap so probably best to only have one child.

see lua.wetgenes.gamecake.widgets.meta.setup for generic options

If not explicetly set we will use a size of "full" ie the size of parent as that is probably how this class will always be used.

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local widget=master:add{class="checkbox",...}

A button that can be used to display and toggle a single bit of data.

We catch and react to the click hook as we can toggle the data_mask bit in the data.

see lua.wetgenes.gamecake.widgets.meta.setup for generic options

As a button we always need to be solid so this is forced to true.

cursor will be set to "hand" if it is not already set so you can tell it is a button when you hover over it.

data_mask defaults to 1 and represents the bit (or bits) that should be tested and toggled in the data. The default of 1 and assuming your data starts at 0 means that the data will toggle between 0 and 1 using this checkbox.

text_false defaults to " " and is the text that will be displayed when a data_mask test is false.

text_true defaults to "X" and is the text that will be displayed when a data_mask test is true.

this function will also call lua.wetgenes.gamecake.widgets.meta.update

If we have a data assigned to this checkbox then make sure that the displayed text is up to date. We should really hook into the data so any change there is copied here instead?

We use data_mask to check a single bit and then set the text to either text_false or text_true depending on the result.

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local data=master.new_data{}

A number or string that can be shared between multiple widgets given basic limits and watched for changes.

This alows the same data to be linked and displayed in multiple widgets simultaneously.

adjust number (may trigger hook)

get display pos, given the size of the parent and our size?

how wide or tall should the handle be given the size of the parent?

adjust number (may trigger hook)

set a number value and min/max range probably without any triggers

given the parents size and our relative position/size within it update dat.num and return a new position (for snapping)

get a number from the string

get a string from the number

set number (may trigger hook unless nohook is set)

Handle a collection of data (IE in the master widget)

Helpers to define defaults for each class of widget

handle a collection of dialogs that all live in the same place

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local widget=master:add{class="drag",...}

A button to drag arround.

local master=oven.rebake("wetgenes.gamecake.widgets").setup()
local widget=master:add{class="paragraph",...}

A layout class for a paragraph of wordwrapped text that ignores quantity of whitespace and possibly child widgets insereted into the text and apropriate control points.

We will be the full width of our parent and as tall as we need to be to fit the given text.

see lua.wetgenes.gamecake.widgets.meta.setup for generic options

master=oven.rebake("wetgenes.gamecake.widgets").setup()

master=oven.rebake("wetgenes.gamecake.widgets").setup(
    {font="Vera",text_size=16,grid_size=32,skin=0} )

Create a master widget, this widget which is considered the root of your GUI. It will be filled with functions/data and should contain all the functions you need to add data and widgets.

You can pass in these configuration values in a table, the example shown above has soom good defaults.

font="Vera"

The default font to use, this must have already been loaded via wetgenes.gamecake.fonts functions.

text_size=16

The default pixel height to render text at.

grid_size=32

The size in pixels that we try and create buttons at.

zone_scene = require("wetgenes.gamecake.zone.scene")

Manage a simple structure to help group, update and draw discrete game objects.

This module contains only one function which can be used to create a scene instance and the rest of this documentation concerns the return from this create function, not the module

scene = zone_scene.create()
scene = zone_scene.create( { sortby={"first","second",...} } )

Create and return a scene object. A base object can be passed in and will be filled in and returned. This can used to supply a sortby table to help control the order of updates of different castes.

If passed in sortby is a table of [caste_name]=weight values to help control the order of updates by caste and make it consistent. For instance you might find it useful to force monsters to update before the player.

scene:add(it)
scene:add(it,caste)
scene:add(it,caste,boot)

Add a new item of caste or it.caste to the list of things to update.

The optional boot table contains initialisation/reset values and will be remembered in item.boot. If boot.id is given then we will remember this item with a call to scene.set(id,it)

The actual act of initalising the item from the boot table is left to custom code which ideally should initalize it and then just call scene.add(it) as the auto shortcuts are unnecesary.

scene:call(fname,...)

If fname is a string then that method will be invoked for every item where it exists like so. Only the first item of each caste is tested, if the function exists there then it is expected to exist for all items of a given caste. This enables us to skip entire castes whilst still making all functions optional.

if it[fname] then it[fname](it,...) end

if fname is a function then it will result in every item geting called with that function like so.

fname(it,...)

The calls are always made backwards through the table so that an item can choose to delete itself.

Finally we return the number of calls we made so you can keep track of currently active items.

scene:caste(caste)

Get the list of items of a given caste, eg "bullets" or "enemies"

This list will be created if it does not already exist.

scene.sortby is used to keep this list in order and an empty system will be autocreated if needed.

Copy of the create_values function from the main zone_scene module.

local it = scene:find_uid( uid )

Return the item with the given uid or nil if no such item has been remembered or a nil uid has been passed in.

local it = scene:forget_uid( {uid=uid} )

Remove the item from the map of uids. Returns the item or nil if uid was invalid unset or our map was not pointing to the correct item.

local it = scene:forget_uid( scene.find_uid( uid ) )

Chain with find_uid to forget an item by uid and this is safe even if the item does not exist.

local uid = scene:generate_uid()

local uid = scene:generate_uid(uid)

Simple unique incremental IDs for items to be used instead of pointers, starts at 1 and goes up as items are added.

Ideally you will also need extra code for compacting these ids ( probably as an export, renumber, import cycle ) to stop them getting huge and breaking. So a save/load system which is out of scope for this code.

Generally, unless we are creating and destroying millions of items we will run out of memory way before this number gets too big.

If a uid is passed in then we will return uid+1 and continue on upwards for subsequent calls.

The point of uids is so we can refer to and lazy link items as weak values making it easy to delete an item without worrying too much about where it has been used. So instead of putting the item table inside another item table we can use a uid reference instead.

Good for serialising data as well.

local it = scene:remember_uid( {} )

Remember an item in the uids table, generating a uid and setting it.uid to this value if one does not already exist.

scene:remove(it)

Remove this item, this is slightly expensive as we need to search in a table to find it before calling table.remove which then has to shuffle the table to fill in the hole.

With very dynamic items it can be faster to allocate all the items you need at the start and then flag them on/off rather than add and remove dynamically.

It may make more sense to create a system which handles its own list of objects, such as particles. Then only use the items to keep track of a master particles item that contains many particles and can add/remove/recycle as it sees fit.

scene:reset()

Empty the list of items to update and draw, this does not reset the systems table that should be modified with the insert and remove functions.

scene:sortby_update(newtab)

A function that takes the array part of newtab and reverses the key=value so a simple order list can be provided without any explicit weights. The first caste name in the array gets a weight of 1, second 2 and so on.

Newtab is coppied into scene.sortby for use a s aweight lookuptable of name to weight.

If newtab is not provided then scene.sortby is used by default.

print( scene:status() )

Return a debug string giving details about the system order and current number of items of each caste.

scene.systems={name=system,[1]=system}

A sorted table and lookup by caste name of each system. Table is sorted so it will be traversed backwards, backwards traversal allows the current item to delete itself.

scene:systems_call(fname,...)

For every system call the function called fname like so.

system[fname](system,...)

Returns the number of calls made, which will be the number of systems that had an fname function to call.

If fname is a function then it will be called as if it was a method.

scene:systems_cocall(fname,...)

For every system call the function called fname inside a coroutine like so.

system[fname](system,...)

This function can yield and should do so if it is waiting for another system to do something. All coroutines will be run in a round robin style until they all complete.

Returns the number of calls made, which will be the number of systems that had an fname function to call.

If fname is a function then it will be called as if it was a method.

scene:systems_insert(system)

Insert a new system replacing any system of the same caste. system.caste should be set to the caste of the system for this to work.

system = scene:systems_remove(caste)

Remove and return the system of the given caste.

scene.uids={[uid]=item,...}

A map of currently remembered uids to items.

zone_scene = require("wetgenes.gamecake.zone.scene")

values = zone_scene.create_values()

Create and return a values object.

This is an array of objects representing the main object in values[1] and future predictions in values[2],values[3] etc etc.

The key values in the higher numbers overide key values in the lower numbers so essentially only changes need to be written into the predicted slots.

value=values:get(key)
value=values:get(key,topidx)

Get the current value for this key by searching from the top of the stack to the bottom and returning the first non nil value we find.

If topidx is given then get the value at this idx, this would normally be negative in which it counts back from the end. So it is easy to time travel back a frame into the cached values with -1 as the idx.

value=values:manifest(key,value)

Get the current value for this key if there is no current value then set the current value.

This uses values:get and values:set to perform these actions.

values2 = values:new()

Create and return a new values object with a single slot containing an empty object.

values:pull()

Merge bottom 2 changesets and replae with just 1 shifting all values down one.

values:push()

Add a new slot to the end of the values array. Future values will be writen into this new slot.

values:set(key,value)

If this is different from the current value then write the value into the key of the object at the top of the stack. Hence future gets will get this new value.

value=values:tween(key,tween)

Tween between the current value(1) and the previous value(0).

A tween of 0 gets the previous value, a tween of 1 gets the current value and any other tween will get a mix between the two if that is possible.

We can only mix numbers or tardis values, other values will round to either 0 or 1 whichever is closest and then get that whole value.

value=values:twrap(key,nmax,tween)

Tween wrap between the current value and the previous value.

Result will be in rang of 0>= n <nmax , blended in the shortest direction.

nmax may be a number or a tardis value for nmax per dimension

A tween of 0 gets the previous value, a tween of 1 gets the current value and any other tween will get a mix between the two if that is possible.

We can only mix numbers or tardis values, other values will round to either 0 or 1 whichever is closest and then get that whole value.

values:unpush()

Remove top pushed slot.

Generic game objects, IE things that exist in game and can be interacted with by the players.

Some times these exist in world, sometimes they exist in bags or inventory etc so are not visible world objects.

As such this item always exists here and will be moved in and out of world objects as necessary.