AAF - minimalistic ascii animation framework

Welcome to the AAF GitHub Project Page

This project aims to give end-[power-(?)]users an easy & functional way to experiment with ASCII animations directly from a terminal window. It provides several functions in "some unified way", simplifying further additions & experiments.

Using the framework is intended to be a lot like "Processing ( P5 )" & others (..) for the users to get their grips on it as quickly as possible.

This doc is quite minimalistic, so if you want to use this project, read it thoroughly :)

simplest ( wip ) example possible:

Notes

Each game / project willing to use the framework must be made of at least three files:

• the "ascii_animation__executable.sh" file -- the actual executable ( what to run )
• the "ascii_animation__project.sh" file -- containing the barebone code & yours
• the "ascii_animation__framework.sh" file -- containing the framework itself

In a near future, I am willing to try different "experimental inputs" & add them to the framework, thus providing sort of "event handling" capabilities as an "additional bonus" ;p

Usage

• the "ascii_animation__executable.sh" file:

This file is the actual executable ( the one to run / execute to launch your project ). You can add any infos you'd like as comments, in the dedicated space if possible or at least preceeded by "##". The rest of the file needs to stay untouched for the framework to work correctly ( .. ).

ascii_animation__executable.sh - provided / barebone example

#!/bin/bash
# the above is not actually necessary for me, except of a cleaner debugging / coding ( .. )

####
## -- ASCII_ANIMATION FRAMEWORK --
##
##    Game / Project executable
##
##       <GAME/PROJECT NAME>
##       <GAME/PROJECT TYPE>
##       <GAME/PROJECT INFO>
##      <GAME/PROJECT AUTHOR>
##       <GAME/PROJECT MAIL>
##       <GAME/PROJECT WWW.> 
####

## --
# Import the [tiny & wip] Ascii Animation Framework
source ascii_animation__framework.sh # -- ! MUST BE PRESENT
# Init & launch game/project
_setup # -- ! MUST BE PRESENT
_draw # -- ! MUST BE PRESENT
## --

• the "ascii_animation__project.sh" file:

This file is the one that contains the barebone code for using the framework & your own functions & variables. It MUST contain at least a "setup()" & a "draw()" function. More than necessary, these function are the ones you 'll use for initialization & looping. As their names suggest, the "setup()" function is used for the initializations while the "draw()" function 'll simply enter an infinite loop. To exit that infinite loop, simply hit "Ctrl-C" & you'll be redirected to your prompt ( nb: some "custom cleanup handlers" 'll be added in a near future ( .. ) ).

ascii_animation__project.sh - provided / barebone example

#!/bin/bash
# the above is not actually necessary for me, except of a cleaner debugging / coding ( .. )

####
## -- ASCII_ANIMATION FRAMEWORK --
##
##        Game / Project file
##
####

## --

# you can define your variables and function in below

# "setup()" function - 'll run once at the beginning of the game / project execution -- ! MUST BE PRESENT ( can be empty )
setup(){

  saveContext # save cursor position before drawing
  echo -en "user text in setup() function ..."
  restoreContext # restore the cursor position after drawing

  sleep 5 # wait a little bit for our user to see the message displayed above ( as we're in the "setup()" function, it's ok to invoke the "sleep()" function -> aka it won't mess with the framerate )

}

# "draw()" function - 'll be called repeatedly in an infinite loop until the user hit "Ctrl-C" -- ! MUST BE PRESENT ( can be empty )
draw(){

  saveContext # save cursor position before drawing
  drawCenteredText "Hello World end-user !" # draw a one-line text, centered
  restoreContext # restore the cursor position after drawing

}

• the "ascii_animation__framework.sh" file:

This file is the the framework itself. DON'T MODIFY IT UNLESS YOU REALLY KNOW WHAT YOU'RE DOING ! ( yup, that's a warning .. ). In fact, you should never [ever] need to do so. If you need custom functions ( wich are not already setup system-wide, if you know what i mean -> If you don't, this comment is not for you ), you just have to write them in the "ascii_animation__project.sh" file, right before the declaration of the "setup()" function ( I left a comment there ;) ). If you really, deeply need more space, and to keep a clean "ascii_animation__project.sh" file, what you can do is "source" the "big file" containing you custom code in the "ascii_animation__project.sh" file, right were you'd have declared some custom variables & functions.

ascii_animation__project.sh - example of "sourcing" an external file containing custom code

# ( .. )
# you can define your variables and function in below
# "source" the external file's content
source myexternalfile.sh
# we can also do stuff BEFORE & outside the "setup()" function ( not AFTER it elsewhere )
# that's what we'll do here, as an EXAMPLE ( nb: also, DON'T use "echo" & prefer the framework equivalent )
# display the number held by our variable defined in the external file
displayNumber $aVariable
# echo the text held by another variable defined in our external file
echo -en "$anotherVariable" 

# "setup()" function
# ( .. )

simple example of an external file that'd be "sourced" by the "ascii_animation__project.sh" file ( it is good practice NOT to use names starting with "aaf" or "AAF" -> the framework 'll use these a "namespaces" in the next update of the project ).

#!/bin/bash
# myexternalfile.sh

# declare a variable
aVariable=0
anotherVariable="Hello there .."

# declare a function
displayNumber(){
  echo -en "$1" # echo the first parameter passed
}

Authors and Contributors

StephaneAG ( @StephaneAG )

Support or Contact

Feel free to contact me for any help, suggestion, or related stuff.