Complete CRAFT reference

Timmy_theBarbarian

@dave1707 you probably know how to help me with this:

I’m posting this as a discussion because I’m not seeing an answer to this specifically for CRAFT and having the answer on here will help people in the future:

Ok, so I’ve searched as best I can on the internet, and it seems that the in-app reference material being incomplete is a KNOWN issue. The external sources of further information I have found are extremely helpful but seem to have been made BEFORE craft was implemented.

Is there a source of complete reference information for craft? Have I missed it? I’m not seeing a discussion that points to the answer.

I’m currently reverse engineering the voxel system to make my own.

This line has two issues:

scene.voxels.blocks:addAssetPack("Blocks")

1: the reference in craft doesn’t tell me about it.
2: the output when playing the block library says “asset strings are deprecated”

I know what it does, it adds an asset pack the the blocks stored in the voxel system.

So I’m looking for the reference to see what the proper call is, and what it is expecting, and the reference is incomplete.

It’s less about knowing what it does, but having access to the reference to understand fully HOW it does it.

Help?

-Timmy_theBarbarian

dave1707

@Timmy_theBarbarian What you see is what you get. There isn’t very much documentation for Craft other than what you find in Codea which doesn’t give much. As for the “asset strings are deprecated”, that’s because the way assets are now used was changed since the blocks demo was created. The blocks demo hasn’t been updated to correct the deprecated warnings.

Timmy_theBarbarian

That’s what I figured. Do you use craft all that much? Have some hack code I can reverse engineer?

My intention now is to put together a reference of my own to share with the community.

Any help from anyone will be greatly appreciated!

I’m assuming the source isn’t available? I could tear through that and make a reference library from my findings.

dave1707

@Timmy_theBarbarian I have a lot of Craft code, but nothing as complicated as the Craft examples which is probably a good place to reverse engineer. I once asked for a Craft doc in the form of a Tree diagram so I could see how all the Craft commands are related to each other. That didn’t go anywhere.

Timmy_theBarbarian

I have started with the examples. A tree diagram is smart. That will be how i present it. I’m too dedicated to this tool to not have this information.

Do you have any simplified craft code that uses the voxel engine specifically? If so please PM me with it. It will help me get my bearings with the system as a whole and I can use the examples to fill in the rest.

RonJeffries

Codea is cool, but if people can't figure it out, will they stick around? will they tout it to others?

Timmy_theBarbarian

Fact. I am currently constructing the flow tree aforementioned by @dave1707

I’m making 2.

1 == everything under craft

2 == a “project” tech tree from start to finish showing all the requirements for a base working program with the tree noting the parent - child relationships.

THAT will be sufficient me thinks

Bri_G

@Timmy_theBarbarian - would love to see these when you have completed them. Started my own ages ago, but like many of my projects it got shelved.

Curious - what package are you building this in ? I was using iThoughts (I think).

UberGoober

@Timmy_theBarbarian I don’t know how helpful this would be—potentially a lot, potentially not—but I had to wrangle with Craft a lot to create a texture pack:

https://codea.io/talk/discussion/11843/complete-craft-texture-pack

I think a had to figure out at least one or two undocumented features, in particular the syntax for creating non-cube-shaped blocks, such as the piston and the cactus and the sign.

Bri_G

@Timmy_theBarbarian - found it, this is as far as I got (before my usual distraction hit me).

Timmy_theBarbarian

@Bri_G Excellent. This will speed things up. You focused on things I haven’t got to yet so it will help streamline the process. Thank you. I’m using MindNode for the maps. Haven’t decided how/if I will make the reference library. May not dedicate the time to a full reference. I am fully convinced @Simeon and friends will finish updating the reference library in future versions. In fact i am convinced that they have considered this need and have concluded that with the combined expressed information within the reference library, the code examples nested within said library, and the HORRIBLY commented examples provided with the shipped product, that we have all/most of the information required to utilize the tool in an at least good enough for now format.

@UberGoober I will pour over this and assimilate the information. Thank you good sir.

UberGoober

Another pertinent element is that sooner or later Codea 4 will come along and IIRC it will revamp both the 2D and 3D APIs. They say it will take a while but that’s a statement that’s open to interpretation.

Bri_G

@Timmy_theBarbarian - you're welcome. I have always struggled with the hierarchy involved in Craft and wanted to understand it better. I'll probably revisit this sometime with a little more focus - like what you need to produce (and in what order) to create an object. Also things like applying multiple textures or complex models involving several objects. Things that I haven't fully cracked yet.

Timmy_theBarbarian

@UberGoober PRECISELY. I considered the idea of not worrying about it and muddling through. Then I realized I would be muddling in order to get to this level of understanding anyway. So I might as well make it comprehensive. The revamp will be welcome. Historically codea has always improved itself. I just hope it has code folding

@Bri_G EXACTLY! I want to understand how it WORKS. not how to get it to work.

UberGoober

@Timmy_theBarbarian in @John’s demo video of Craft there was a block that didn’t make it into the final release. It looked like a white spinning geodesic ball. It’s possible the code for that still exists even though it never got implemented—if you ever come across it please let me know!

Steppers

@Timmy_theBarbarian I’ve no idea if this will be of any use to you but here it is anyway:

function gen_docs(table_name)
    local f = io.open((asset.documents .. "docs_" .. table_name .. ".txt").path, "w")

    -- Track processed values to avoid infinite recursion
    local processed = {}

    local function tree(key, v)
        processed[v] = true
        for kn,vn in pairs(v) do

            -- We can't concatenate a userdata value
            if type(kn) == "userdata" then
                kn = "<userdata>"
            end

            local t = type(vn)    
            if t == "table" and not processed[vn] then
                -- Recurse
                tree(key .. "." .. kn, vn)
            else
                -- Add listing
                f:write(key .. "." .. kn .. ": " .. t .. "\n")
                f:flush()
                processed[vn] = true
            end
        end
    end

    tree(table_name, _G[table_name])
    print("table listing written to 'docs_" .. table_name .. ".txt'")
end

function setup()
    gen_docs("craft")
end

This generates a full listing of everything contained in the craft table (including sub-tables) in Codea’s documents directory as ‘docs_craft.txt’

Steppers

Alternatively, this will list everything globally accessible in a Codea Project:

function gen_docs(table_name)
    local f = io.open((asset.documents .. "docs_" .. table_name .. ".txt").path, "w")

    -- Track processed values to avoid infinite recursion
    local processed = {}

    local function write_listing(key, value)
        if type(value) == "table" then
            f:write(string.format("%s = table: %p\n", key, value))
        elseif type(value) == "string" then
            f:write(string.format("%s = \"%s\"\n", key, value))
        else
            f:write(string.format("%s = %s\n", key, value))
        end
    end

    local function tree(key, v)
        processed[v] = true
        for kn,vn in pairs(v) do

            -- We can't concatenate a userdata value
            if type(kn) == "userdata" then
                kn = "<userdata>"
            end
            kn = key .. "." .. kn

            -- Write to file
            write_listing(kn, vn)

            local t = type(vn)
            if t == "table" and not processed[vn] then
                -- Recurse
                tree(kn, vn)
            end

            processed[vn] = true
        end
    end

    tree(table_name, _G[table_name])
    f:close()
    print("table listing written to 'docs_" .. table_name .. ".txt'")
end

function setup()
    gen_docs("_G")
end

This one also lists the values themselves.

dave1707

Here’s a version of the first program that lists the contents to the screen. It’s sorted and can be scrolled up or down.

viewer.mode=FULLSCREEN

function setup()
    textMode(CORNER)
    fill(255)
    tab={}
    dy=-40
    gen_docs("craft")
    table.sort(tab)
    table.insert(tab,1,#tab.."  Table entries")
end

function draw()
    background(0)
    for a,b in pairs(tab) do
        text(a.."   "..b,20,HEIGHT-a*20+dy)
    end
end

function touched(t)
    if t.state==CHANGED then
        dy=dy+t.deltaY
    end
end

function gen_docs(table_name)
    local processed = {}    
    local function tree(key, v)
        processed[v] = true
        for kn,vn in pairs(v) do            
            if type(kn) == "userdata" then
                kn = "<userdata>"
            end           
            local t = type(vn)    
            if t == "table" and not processed[vn] then
                tree(key .. "." .. kn, vn)
            else
                table.insert(tab,key .. "." .. kn .. ": " .. t)
                processed[vn] = true
            end
        end
    end    
    tree(table_name, _G[table_name])
end

UberGoober

@Timmy_theBarbarian undocumented function, I think, for blocks: schedule(amount)

It’s used three times, I think, in the Block Library project, which is where the attached screenshot comes from.

Not sure what it does—I mean it’s obvious that it’s involved with scheduling something—I just don’t understand how it works.

Timmy_theBarbarian

@Steppers i could kiss you.

@dave1707 thank you for the assist!

@UberGoober thank you for bringing that to my attention! If I can trace it back properly I’ll include it for sure!

Thank you guys for the assistance! I’ll keep at it!

Bri_G

All,

Just for a laugh - modified and reposted a demo by @dave1707 with a Starwars theme, but angled at Craft (tongue in cheek).

Background image free from ‘Unsplash’ with this attribution Also in graffiti name.

UberGoober

@Bri_G NSFIPhone sadly

dave1707

@UberGoober Not sure what you’re saying (NSF), but I’m assuming it doesn’t work on your iPhone. I made this change to get it to work on my iPhone 8 SE.

In the draw function.

sprite(galaxy,WIDTH/2,HEIGHT/2,700,400)

UberGoober

@dave1707 I was making a dumb play on words, like instead of NSFW it’s NSFIPhone. Dumb I know.

Timmy_theBarbarian

i thought it was clever

UberGoober

OK here’s what I think schedule does. It’s a function that can be called on voxel blocks to trigger their blockUpdate function a certain number of ticks from now. It’s useful for custom-scripted blocks.

Timmy_theBarbarian

Oh nice! That’s super useful!

Update: I’m still working on this on the weekends. My day job takes a lot of time and energy so it will take a while

UberGoober

In the 3D Asset Viewer there’s a bunch of undocumented stuff in this one place, I think:

            local b = v:get(craft.renderer).model.bounds
            b2 = bounds(b.min, b.max)
            b2:translate(v.position)
            scene.debug:bounds(b2, color(255,255,255,255))

I may be missing this stuff in the documentation, but it looks to me like there are undocumented features on every line here, starting with model.bounds, then bounds(min, max), then bounds:translate(position), and then scene.debug:bounds(bounds, color).

Timmy_theBarbarian

yeah that’s exactly the problem. its undocumented everywhere. gonna take a lot of time to put together.

John

Hey guys,

This is my fault since I added things to Codea/Craft here and there but failed to document all of them. I'm really awful at missing this kind of thing. Sorry it's become such a bother for everyone

As a way to help sort out this mess I've created a repository over at https://github.com/JohnTM/Codea-Docs which has all the existing documentation and the source code for the Craft lua bindings, which contains literally every Craft API call that exists (please mind the messy code). It doesn't say exactly what everything does but I can help illuminate that as well if anyone has a specific question

I've tried writing comprehensive documentation, manuals, tutorials, videos etc... before but along with juggling bug fixes, updates and new app releases (such as Shade), and my full time job I do find it hard to maintain motivation and consistency across the board. And for that I do apologise since this community means a lot to me

• John

dave1707

@John Thanks for the link. There’s a lot to look at.

UberGoober

@John thanks for dropping in to explain stuff!

The silver lining to me is that it’s fun to discover new things that Craft can do.

John

@dave1707 no worries. Yeah the bindings and documentation are massively monolithic. I guess that's what happens when you keep adding to a project for this many years. Codea 4 has a much cleaner and elegant design, which will supersede this at some point

@UberGoober no worries. I do feel bad but its been pretty amazing how you guys have reverse engineered the undocumented stuff!

UberGoober

I’m not great at deciphering the bindings—my burning question is if the Craft shader format supports vertex buffers for variables—can anyone tell?

John

@UberGoober I'm not entirely sure what you mean? Craft doesn't support arbitrary extra mesh buffers like the old shader system if that's what you mean. You can use array uniforms to pass in an array of points though if that's what you want

UberGoober

I think we’re on the same page: in the old shaders every variable could be buffered with a different value for every vertex, making some really amazing things possible.

People did some amazing shader stuff in the old days and the lack of those buffers is what’s keeping me from porting the most impressive ones, if I recall correctly.

John

Ah ok I see what you mean. Craft unfortunately doesn't have this feature. The only thing you could do really is use the existing uv and color channels to store extra data. I could also add access to the second uv coordinate (currently not in the API). Can you link to examples that used the old shader system so I can see what it looks like?

UberGoober

I don’t know how to do array uniforms is what I’m missing I guess. They need one format in the lua part of the Craft shader and a different format in the shader code, I could never get them to work together.

John

@UberGoober looking into the code now, I noticed that array uniforms was originally a planned feature but never got fully implemented. So that makes sense that you couldn't get it working. I'll look into how hard it would be to finally add that feature

UberGoober

@John that would be great!