Log In  

Understanding ENVIRONMENTS

Inherited from native LUA, _𝘦𝘯𝘷 (NOTE: type it in PUNY FONT, won't work otherwise! For External editors, write it in CAPS _ENV so it transfers as PUNY FONT inside PICO-8) can be a tricky feature to understand and use (abuse?). There's been some talking around this subject and as I am actually using it heavily in my coding style (very OOP I'm afraid...) I thought I could share some knowledge around it.

If we take the information directly from LUA's manual what we are told is the following:


As will be discussed in §3.2 and §3.3.3, any reference to a free name (that is, a name not bound to any declaration) var is syntactically translated to _ENV.var. Moreover, every chunk is compiled in the scope of an external local variable named _ENV (see §3.3.2), so _ENV itself is never a free name in a chunk.

Despite the existence of this external _ENV variable and the translation of free names, _ENV is a completely regular name. In particular, you can define new variables and parameters with that name. Each reference to a free name uses the _ENV that is visible at that point in the program, following the usual visibility rules of Lua (see §3.5).

Any table used as the value of _ENV is called an environment.


Cryptic right? Let's try to distil the information...

Let's start with understanding what's a free name. Any declared identifier that does not correspond to a given scope, f.e. GLOBAL variable definitions, API defined symbols (identifiers, functions, etc) and so on, is considered a free name OK... so this starts to get us somewhere! Any time we are using a global scope variable name or an API function call, internally LUA's interpreter is actually converting that to _𝘦𝘯𝘷.identifier. These tables used as values for _𝘦𝘯𝘷 are usually called ENVIRONMENTS.

Let's move into the next part: _𝘦𝘯𝘷 itself is just a local identifier in your current scope, and like any other identifier you can assign anything to it. In particular, you can overwrite the automatically created _𝘦𝘯𝘷 in your current scope, which will always be the GLOBAL ENVIRONMENT, and point it to any table, and from that point on, any free name will be looked for inside that table and not in the _𝘦𝘯𝘷 scope originally received .

Everytime a scope is defined in the LUA execution context, the GLOBAL ENVIRONMENT (on isolated scopes, like function scopes) or the currently active environment (inside language scope constructs) is injected as a local external variable _𝘦𝘯𝘷. That means every function scope, any language scope construct (do ... end, if ... end, etc)

Great! So that's all there is to know about _𝘦𝘯𝘷... but how can we use this to our benefit? Let's find out!

Using ENVIRONMENTS

The core and simplest use-case for ENVIRONMENTS is mimicking WITH language constructs. It's quite typical that you have a table in your game holding all the information of the player... it's position, health level, sprite index, and many others probably. There's almost for sure some place in your code that handles the initialization of the player and that probably looks something similar to this:

player={}
player.x=10
player.y=20
player.lives=3
player.sp=1
-- many more here potentially...

Depending on how many times you need to access the player table you can actually consume a big number of tokens (1 per each access to player). When you have more than 3 (the general cost of redeclaring _𝘦𝘯𝘷) or 4 (the cost if you require a scope definition for it) you can benefit from not needing to repeat PLAYER for every access like this:

player={}

do
  local _𝘦𝘯𝘷=player
  x=10
  y=20
  lives=3
  sp=1
end

The use of the DO ... END block in there prevents that we override _𝘦𝘯𝘷 for all our code, and that this applies only to the lines we want it to apply.

This technique is particularly useful if you use an OOP approach where you pass around SELF as a self-reference to table methods and will reduce drastically the need to repeatedly use SELF everywhere:

player={
 x=10,
 y=20,
 lives=3,
 sp=1,
 dead=false,
 hit=function(self)
   local _𝘦𝘯𝘷=self
   if not dead then
     lives-=1
     if (lives==0) dead=true
     sp=2 -- dead sprite
   end
 end
}

?player.lives
player:hit()
?player.lives

You can even reduce the need for the override this way (thank you @thisismypassword for the contribution):

player={
 x=10,
 y=20,
 lives=3,
 sp=1,
 dead=false,
 hit=function(_𝘦𝘯𝘷)
   if not dead then
     lives-=1
     if (lives==0) dead=true
     sp=2 -- dead sprite
   end
 end
}

In a sense, this is very similar to WITH language constructs in other programming languages like Object Oriented BASIC or PASCAL. The benefit: reduce token count and char count. But don't just jump blindly into using this, get to the end of this post and understand the associated drawbacks!

Drawbacks of using ENVIRONMENTS in PICO-8

The main drawback for using an overriden ENVIRONMENT is loosing access to the GLOBAL ENVIRONMENT once we replace _𝘦𝘯𝘷 in a particular scope. When that happens, we stop seeing global variables and all API and base PICO-8 definitions, so we won't be able to call any function, use glyph symbols or access global vars. Luckily, METATABLES can help us here taking advantage of __INDEX metamethod.

METATABLES can be defined as a PROTOTYPE for other tables, and apart from defining elements to inherit in ohter tables, they can also define the BEHAVIOUR of these tables using METAMETHODS. Those are a quite advanced feature in LUA and I won't cover them in this post but for __INDEX that is going to be our solution for keeping our access to the global scope even if we have overriden our ENVIRONMENT (at a small performance cost...)

__INDEX METAMETHOD defines the behaviour of a table when we try to access an element that is not defined in it. Try this code to have a clear example of what it does:

d=4

mytable={
a=1,
b=2,
c=3,
}

setmetatable(mytable,
 {
 __index=function(tbl,key) 
  stop("accessing non existent key "..key.."\nin table "..tostr(tbl,true)) 
 end
 })

?mytable.a
?mytable.b
?mytable.c
?mytable.d

__INDEX can be defined as a function or as a TABLE that will be where the missing identifier will be searched for... and there's our solution, just redefine __INDEX as _𝘦𝘯𝘷 and our problem is solved:

d=4

mytable={
a=1,
b=2,
c=3,
}

setmetatable(mytable,{__index=_𝘦𝘯𝘷})

?mytable.a
?mytable.b
?mytable.c
?mytable.d

If we apply this approach to our previous example we can do things like this:

player=setmetatable({
 init=function(_𝘦𝘯𝘷)
   x=10
   y=20
   lives=3
   sp=1
   w=2
   h=2
   fliph=false
   flipv=false
   dead=false
 end, 
 draw=function(_𝘦𝘯𝘷)
   cls()
   spr(sp,x,y,w,h,fliph,flipv)
 end,
 update=function(_𝘦𝘯𝘷)
   if btnp(⬅️) then 
     if (x>0) x-=1
     fliph=true
   elseif btnp(➡️) then
     if (x<128-8*w) x+=1
     fliph=false
   end
 end, 
 hit=function(_𝘦𝘯𝘷)
   if not dead then
     lives-=1
     if (lives==0) dead=true
     sp=2 -- dead sprite
   end
 end
},{__index=_𝘦𝘯𝘷})

That's a very basic OOP-like approach to have entities inside your games, that expose entity:update() and entity:draw() methods you can call in your game loop (like having a list of entities in a table and iterate it calling update() and draw() for each entity inside your _update() and _draw() functions).

There is another effect that loosing access to the GLOBAL ENVIRONMENT generates, and this one is not fixed by __INDEX. Any new free name we create will be created inside the active ENVIRONMENT, so we won't be able to create any new GLOBAL variable from within the scopes affected by the override. If you need to be able to access the global space, one easy option is have a global variable pointing to the GLOBAL ENVIRONMENT in your code. Natively, LUA has _G environment available everywhere, but this one is not present in PICO-8, so you will need to create your own.

-- used by __index access
_g=_𝘦𝘯𝘷

mytable=setmetatable({
a=0,b=0,c=0,
init=function(_𝘦𝘯𝘷) 
 a,b,c=1,2,3
 newvar=25 -- this is created in mytable
 _g["initialized"]=true -- this is created in GLOBAL ENVIRONMENT
end
},{__index=_𝘦𝘯𝘷})

mytable:init()

function _draw()
  -- outside table scopes (no __index access)
  local _g,_𝘦𝘯𝘷=_𝘦𝘯𝘷,mytable
  if _g.initialized and _g.btnp()>0 then
  a+=1
  b+=1
  c+=1
end

cls()
?tostr(initialized)..":"..mytable.newvar..", "..mytable.a..", "..mytable.b..", "..mytable.c
end

Other uses

There's many more uses you can find for using ENVIRONMENTS... shadowing and extending the GLOBAL ENVIRONMENT, some Strategy Pattern approach (f.e. having several tables with alternate strategies extending the global scope and switching between them...). Don't be afraid to experiment! The basics are all here, the limits are yours to find!

P#116282 2022-08-25 20:12 ( Edited 2022-09-01 10:51)

3

Great writeup!
Instead of writing function(self) local _𝘦𝘯𝘷 = self, though - you can instead just write function(_𝘦𝘯𝘷).
This has the same effect since function parameters are really just locals, and it's shorter.
You can do the same trick with for _𝘦𝘯𝘷 in all(something), by the way.

P#116310 2022-08-26 05:23 ( Edited 2022-08-26 05:25)

@thisismypassword good trick... will add that to the post as alternatives... did not ocurr to me that would work :) Thnx for pointing them out!

P#116311 2022-08-26 06:23 ( Edited 2022-08-26 06:23)

Wow great write up. This is really helpful.

P#116312 2022-08-26 08:38

Thnx @SquidLight I just tried to give a simple approach to _env :)

P#116313 2022-08-26 09:55
:: shy

Excellent writeup! This goes through everything you need to know, and ends with a very solid (and simple) example of usage. It's always great when someone puts in the time to demystify something into a BBS post like this, and I really respect the effort here to not only explain a new tool, but use it well.

P#116319 2022-08-26 14:00

THnx @shy, I've been through so many conversations in Discord about _env I thought it was time to dump all that into a post that could help out to propagate the knowledge.

P#116328 2022-08-26 16:23

Just added extra info on GLOBAL ENVIRONMENT access & var creation that was missing.

P#116329 2022-08-26 17:03

Wait, if I'm understanding this correctly, then it's the best token optimization I've ever heard? And it makes your code more readable and more amendable to OOP approaches like the update pattern?

God, I thought I knew Lua but this was eye-opening, thank you.

P#116591 2022-08-30 16:44
:: merwok

yes and no! it helps saving a ton of thing. tokens for code that’s already written in a object-oriented style, possibly also entity-component systems, but won’t do anything for code that uses closures (function that has local variables and return functions that work with these local vars) or global objects (messy, I know!).

all games use the update pattern, but not necessarily in an OO way :)

P#116595 2022-08-30 17:04

@shastabolicious glad it helped you out to understand environments. If your style is OOP friendly this and particularly combining it with __call can do wonders ;) I will write another post on my approach to an entity system (that is a bit... convoluted)

P#116604 2022-08-30 18:49 ( Edited 2022-08-30 18:50)

Good point, @merwok. Do you know any games making heavy use of closures or other functional programming tricks? I'd love to read their source.

P#116609 2022-08-30 19:34 ( Edited 2022-08-30 19:35)
:: merwok

freds72 for one likes closure style!

P#116667 2022-08-31 17:23

Good write up on _ENV @slainte. Possibly worth pointing out for people using external editors that _ENV should be capitalized but will appear in puny font inside of the pico-8 editor. That's probably already common knowledge but I have seen a few people get tripped up by it from time to time.

@shastabolicious, you might be interested in the curried functions utility I posted a while back. It's probably not super useful/practical in a pico-8 context but it's implemented using closures and higher-order functions and it's quite short.

P#116722 2022-09-01 10:40

Thnx @jasondelaat, will add the note... it never hurts ;)

P#116725 2022-09-01 10:50
:: Felice

@slainte:

Maybe this is a stupid question, but why did you set _g.["initialized"] instead of just _g.initialized? They're equivalent.

Also the _g here in _draw() seems to be unnecessary, since the table you're assigning to _env contains a metatable with an __index that contains _g. It might gain you a small perf upgrade by having a local cache of _g in an inner loop, but there's otherwise no need for the token expenditure.

  local _g,_𝘦𝘯𝘷=_𝘦𝘯𝘷,mytable

Oh wait, maybe you meant to say it'd be useful for tables that don't have the metatable? I can see how you might have been iteratively writing up example code and then thought to yourself "Wait, I don't need two tables here, I can just use the first one," while forgetting the reason you'd set up the second. Is that what happened?

P#117828 2022-09-23 00:59

Hey @Felice, thank you for the comments...

About the [] access vs the . access you are right, they are equivalent... just used different access methods (as there's _g.initilized inside _draw) to show all the options

For the initialization of _G, you are also right, but it was written like an isolated example in mind for when you have a function (not a table) and need to access globals without having the option to use __index. Ended up a bit messed as it mixes table/non-table _env overrides and that renders some of the code useless... I will maybe split that into 2 separate examples with a table without __index involved.

Thnx for pointing those out!

P#117841 2022-09-23 06:04

[Please log in to post a comment]

Follow Lexaloffle:        
Generated 2022-09-26 21:54:10 | 0.098s | Q:38