Share Your Code

Crawl Space Library

Posted by AdamBucketz, Posted on March 29, 2011, Last updated April 21, 2011

Hey all,

I'm finally getting around to submitting this! I know many of your are already using it, but for folks who aren't following me on Twitter ( @AdamBuchweitz ), here is a link to the Crawl Space Library. It's open source and on GitHub here: http://github.com/AdamBuchweitz/CrawlSpaceLib and you will find the management site here: http://library.crawlspacegames.com where you can see the latest activity, submit bugs, ask questions, find out the latest news.

There is a stable branch that has been circulating for a while, and a beta branch. The beta branch has a LOT more features, but I haven't had enough people test it in their projects to consider it stable enough to merge into the master.

I'm working on tutorials / screencasts to demo everything the library can do for you, and those will also be on the wiki site, but until then everything is documented in the library, and here is an abridged list of included features:

Feature List:
+ Global variables for dynamic resolution
+ Super simple saving and loading
+ Shortened reference points, passible as arguments to all display objects
+ Insert multiple objects into a group
+ Automatic retina-ready text
+ Paragraphs
+ Exposed API: timer.cancelAll()
+ Safe timer.cancel()
+ Crossfade background audio
+ Play SFX based on registered true/false variable
+ Simulator-friendly webPopups
+ Print installed font names with printFonts()
+ Initialize and globalize a font with one line
+ Execute a function if internet is detected, execute another if not connected
+ Global information handling
+ Extended print statement
+ Pass colors as hexes for setting fill and text color

Beta Feature List:
+ Debugger tool
|\
| + On-screen print statements
| + Post-launch variable manipulation ( requires CoronaUI )
| + FPS / Memory consumption dialog
|
+ 'Enable' feature for Debugger, easy OpenFeint, Analytics, etc
+ table.shuffle
+ table.search
+ Safe transition.cancel
+ Much more coming!

and here is a sample main.lua file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
            --[[ ########## Require ########## ]]--
 
local CSL = require "crawlspaceLib"
 
            --[[ ########## Init Font Demo ########## ]]--
 
initFont("FlyerLT-BlackCondensed", "flyer")
 
            --[[ ########## New Paragraph Demo ########## ]]--
 
local format = {}
format.font = flyer
format.size = 20
format.lineHeight = 1.4
format.align = "center"
format.textColor = {"ffffff"}
 
local myParagraph = display.newParagraph( "Welcome to the Crawl Space Library!", 15, format)
myParagraph.x, myParagraph.y = centerX, screenHeight*.2
 
            --[[ ########## Help Demo ########## ]]--
 
CSL.help("newParagraph")
 
CSL.help()
 
            --[[ ########## Timer Demo ########## ]]--
 
 -- This will never fire because it's cancelled
local outputMessage = function()
    print("Timer 1 activated!")
end
 
 -- This WILL fire because it's told not to be a part of the cancelAll cache
local outputMessage2 = function()
    print("Timer 2 activated!")
end
 
timer.performWithDelay(500, outputMessage )
timer.performWithDelay(1000, outputMessage2, false )
 
timer.cancelAll()
timer.cancel(myNonexistentTimer) -- Cancelling a nil timer does not break your app
 
            --[[ ########## Multiple Transition Demo ########## ]]--
 
local mySquare, myCircle
local mTrans = function()
    mySquare = display.newRect( 10, 20, 10, 10 )
    mySquare.onComplete = function() print("transition 1") end
    mySquare:fadeIn()
 
    myCircle = display.newCircle( screenX + screenWidth - 10, 20, 5, "tr") -- Set the reference point as an argument
    myCircle.onComplete = function() print("transition 2") end
    myCircle:fadeIn()
 
    -- The new "targetSelf" params will target the onComplete table listener of each source
    transition.to({mySquare, myCircle}, {time=5000, y=screenHeight - 20, targetSelf=true})
end
timer.performWithDelay(1500, mTrans, false)
 
            --[[ ########## Multiple Inserts Demo ########## ]]--
 
local group = display.newGroup()
group:insert(myParagraph, mySquare, myCircle)
 
group:fadeIn()
 
            --[[ ########## Internet-Based Functions Demo ########## ]]--
 
local webz = function()
    print("Congrats! You have a connection to the internet!")
end
 
local noWebz = function()
    print("Sorry, you are not connected to the internet.")
end
 
executeIfInternet(webz, noWebz)

The reason I am not posting the library itself is because I update it very frequently and constantly updating this post so often is not very feasible... and it's over 1300 lines...

Hope you all enjoy it!


Replies

0x90
User offline. Last seen 2 days 15 hours ago. Offline
Joined: 19 Oct 2010

Thank you for making this available.
I've been using your library for the past 3 weeks and it makes many common tasks much easier.
Especially the ability to print tables makes debugging so much easier.

andyhullinger
User offline. Last seen 5 weeks 5 hours ago. Offline
Joined: 23 Feb 2010

+1 tableshuffle!!

This library has been a great help for my personal projects. Thanks Adam, Brock, and everybody at crawlspace.

kennw
User offline. Last seen 4 days 12 hours ago. Offline
Joined: 9 Jan 2011

*thumbsup* Adam. Thanks for maintaining this awesome lib.

Stephen Lewis
User offline. Last seen 13 hours 24 min ago. Offline
Joined: 24 Sep 2010

Many incredibly useful features. And a bunch of them "just work" as soon as you include the library. Thanks a bunch!

AdamBucketz
User offline. Last seen 2 days 4 hours ago. Offline
Joined: 10 Dec 2010

Thanks everybody for the kind words, and the votes! So glad you're getting good use out of it.

I posted the first screen cast today demonstrating how to set up your project with the library, while keeping it easily updated. http://bit.ly/h0y89o

I even enhanced a feature for the video =) Next screen cast in the line up is on data saving and loading.

puresimmer
User offline. Last seen 7 weeks 1 hour ago. Offline
Joined: 10 Nov 2010

When I "require" the latest version of this module, it never makes it back to my main.lua.

Is there anything I am missing?

Using the latest official 484 Corona release and the latest of the Beta branch of CSL on GitHub.

BTW, from what I can tell, the lib looks awesome.

AdamBucketz
User offline. Last seen 2 days 4 hours ago. Offline
Joined: 10 Dec 2010

Hello @puresimmer,

What do you mean my it never making it back to your main.lua?

If you set up your project like the sample main.lua above, you should be ok. If you're expecting it to behave like a "module" in the Lua-specific way, it will not. It isn't actually a module, just a Lua library.

puresimmer
User offline. Last seen 7 weeks 1 hour ago. Offline
Joined: 10 Nov 2010

Thanks, I figured it out. You draw a dependency on coronaui now and all those files need to be in the project folder (or Symlinked).

Once I dropped the coronaui stuff in, I was fine. You maybe could consider some sort of "if android" kind of check, if that is not too much trouble.

Thanks.

AdamBucketz
User offline. Last seen 2 days 4 hours ago. Offline
Joined: 10 Dec 2010

Wow you really meant current! I pushed that update probably just an hour or so before you grabbed it. I'm so sorry about that... I'm working on a solution - I really really really do NOT want the CSL to have any dependencies, but that feature is using CoronaUI for post-launch variable manipulation. It's BRAND new, not even announced yet, so you're likely the first to know it exists. I just pushed an update that removes the dependency - still dependent for post-launch manipulation but other than that you're fine without it.

But, *ahem* since you've discovered this new feature, let me explain it a bit. After you require the library, throw this line in:

1
Enable("debug")

Now you have access to the on-screen debugger. Launch your app, hold your finger (or cursor) on the screen for a moment and you'll see a wheel. Tap the middle circle to close it, the top button for fps/memory consumption, left button for on-device print statements (not on the simulator), and the bottom button for the post-launch variable manipulation (The right button will be a user-attached function so you can hook in your own post-launch function). By default, the only adjustable variable is how long you need to hold your finger on the device before the debugger pops up, but you can add your own!

Use this line somewhere in your app to add it to the list:

1
DebugVar(variableName, {min, max}, initialValue [, title ])

So if you wanted to adjust the variable... curLevel, and there are 20 levels, and you want to start with it on level 3:

1
DebugVar("curLevel", {1,20}, 3, "Current Level")

This ties in to the global info handling already in place in the CSL, so to retrieve the curLevel variable you would use getVar("curLevel")

I'm so stoked for this feature, and we have already used it heavily to balance the game we're working on now. I hope everyone else finds it useful too!

a.

Cairo
User offline. Last seen 37 weeks 4 days ago. Offline
Joined: 20 Jan 2011

This looks good! Great job!
I just thought i might mention that library.crawlspacegames.com doesn't work at the moment.

AdamBucketz
User offline. Last seen 2 days 4 hours ago. Offline
Joined: 10 Dec 2010

D'oh!

Thanks @Cairo , we've been moving servers around and experienced a little downtime... should be back up now.

And thanks to everyone for the votes!

gregh@awana.org
User offline. Last seen 2 years 23 weeks ago. Offline
Joined: 9 Nov 2010

Fantastic stuff!

gregh@awana.org
User offline. Last seen 2 years 23 weeks ago. Offline
Joined: 9 Nov 2010

Fantastic stuff!

benny.gortez
User offline. Last seen 1 year 47 weeks ago. Offline
Joined: 13 Mar 2011

This is awesome! Your comments in the code make it easy to understand. Thanks Adam!

photos
User offline. Last seen 2 years 21 weeks ago. Offline
Joined: 4 Apr 2011

Hi, this is great!

I've got a couple of questions about display.newParagraph though:

How can I enter a new line in a paragraph?

\n doesn't seem to work, nor does entering a few return key strokes( messes up the formatting)

How can I get the pound (british sterling) sign to show up?

(I get a nasty little question mark symbol at the moment)

Oh and http://library.crawlspacegames.com/ is down at the moment...

Thanks!!!

monkey
User offline. Last seen 2 years 16 weeks ago. Offline
Joined: 12 Jul 2011

"How can I enter a new line in a paragraph?
\n doesn't seem to work"

I have same issue - works on simulator but not on device(ipad) any one got a fix or solution its the only thing stopping me at the moment!

bradido
User offline. Last seen 1 day 19 hours ago. Offline
Joined: 21 Jun 2011

This is awesome and has a ton of nice features. Thanks so much.

Regarding the overwrite of the newText, I tried using this but it misalign my text when I go between scenes with Director. First time looks correct, leave a scene and come back and it's misaligned. If I comment out CSL the problem goes away.

Also it looks like it does not accept the parent object argument of newText?

It also misaligns my modals and such. Maybe due to the newGroup overwrite?

gtt
User offline. Last seen 21 weeks 6 days ago. Offline
Joined: 2 Aug 2011

We had the same issue. Turns out the newParagraph function splits the text with space as a delimiter.

The solution is to start each line with a new space and end each line with a space as well.

AdamBucketz
User offline. Last seen 2 days 4 hours ago. Offline
Joined: 10 Dec 2010

Hey guys, sorry about the lack of a response to this thread.

I think you'll find that the "\n" issue has been fixed in the up-to-date version on the GitHub repository. We released a book app just last week using it so I'm comfortable claiming that it's production-ready. You shouldn't need to do any work-arounds anymore.

@bradido I've added the parent-as-first-argument support for all the display objects.

The misaligning text elements are likely the result of the scaling for retina text. I have some ideas to fix that, but for the time being all development of the library has halted to facilitate a *major* restructure. I've been getting some help lately and I'm hoping more folks will feel like contributing via GitHub and we can see some really cool stuff happen.

lhvio89
User offline. Last seen 2 years 4 weeks ago. Offline
Joined: 12 Mar 2011

Hey!

First off, LOVE LOVE LOVE using this library. Really, it's awesome. But I am running into an issue, and was hoping for some help. I'm using the audio crossfade function quite a lot in my app, and it works beautifully. However, pretty much without fail, after 10 or so crossfades, audio streams fail to load. I get the error "WARNING: Failed to load audio sound (blahblah.m4a)" in the terminal.

What would be causing this?

Thanks!
Logan

greg886
User offline. Last seen 2 days 16 hours ago. Offline
Joined: 5 Apr 2012

Can someone provide an example of how to use the table.shuffle function?

Could I use it to "print" out the contents of a table to the console for debug?

EDIT: Posted question here: http://developer.anscamobile.com/forum/2012/04/17/ice-example-how-use-tableshuffle