Stepped away from P8 for a while so I find myself a bit confused about the draw and update behavior.

I am trying to make a game where pieces fall and I am using cicfill to create these.

function build_pill(x,y,color,y2,color2)
	radius=2.2
	x2 = x - 3

	pill={circfill(x,y,radius,color),
				circfill(x2,y2,radius,color2)
		}
		add(pills,pill)

		return pill
end

I call it in update:

function _update()
	cls()
	build_pill(30,30,5,30,9)

end

The cls() function keeps erasing my object. However when I remove the cls() function the screen doesnt look right either.

SO

When is the right place to put the cls() and still be able to draw my shapes?

Thanks!

So, you have two issues here:

First is that you've misunderstood the circfill() function's behavior. When you call circfill(), it immediately draws a filled circle to the screen. It doesn't return an object which is drawn later by the system. Instead, what you would want to do is to create an object yourself that contains the {x,y,radius,color} values:

-- (i assume you have this somewhere that you haven't shown us)
function _init()
    pills={}
end

-- create a pill and add it to the list
function build_pill(x,y,color,y2,color2)
    radius=2.2
    x2 = x - 3

    pill=
    {
        {x, y, radius,color },
        {x2,y2,radius,color2}
    }
    add(pills,pill)

    return pill
end

And then call that function in your _update():

function _update()
    -- add another pill object to the list
    build_pill(30,30,5,30,9)
end

(I notice that you are creating a new pill every single frame here, yet never deleting any, so you will eventually run out of memory. However, I'll assume you realize this and you're going to change it to work differently once you get things working.)

But you'll notice we haven't issued any draw calls, and that's because of the second issue:

The _update() function is where you handle input, logic, AI, etc., but should not contain any drawing code. This is because logic is usually the quickest section of a game, and thus it can be run pretty reliably every single frame. Drawing, on the other hand, can take up a significant amount of time, and if it takes up too much, PICO-8 will start skipping calls to _draw(), but it will still try to make sure _update() is called for every frame that's passed, so that the actual action won't slow down, just the framerate.

So, we need to do the drawing inside of _draw(), using those created pill objects' values in calls to circfill():

function _draw()
    -- start by clearing the screen
    cls()

    -- draw the pills...
    for pill_circs in all(pills) do
        -- ...as a series of overlapping circles
        for c in all(pill_circs) do
            circfill(c[1],c[2],c[3],c[4])
        end
    end
end

And obviously you could break out the nested loops inside of _draw() into a tidy function called draw_pills(), but I'll leave that part to you if you want to do it.

Tip: This dual-loop method also allows you to construct longer pills just by adding more {x,y,radius,color} entries inside of build_pill().

Thanks so much!