Photoshop 2025: add layer mask + gradient between two guides via script (AM)

[marcin_1620]

Context: Windows, Photoshop 2025. Horizontal guides already placed; need a vertical black→white gradient between the 3rd and 2nd guides from the bottom, drawn in the active layer mask.

What works: recorded Actions (mask; gradient via pattern workaround).
What I need: a reliable scripted solution to (a) add a standard layer mask if missing and (b) draw that guide-bounded gradient inside the mask.

I’ve tried various snippets found online, but none were reliable (often hitting “Make is not currently available” or “<unknown> menu item not currently available”).

Question: Could you please point me to an official, up-to-date reference of Action Manager events/keys for layer masks and gradients in PS 2025?

[c.pfaffenbichler · Accepted solution]

// gradient on layer mask beween second and third horizontal guide from below;
// 2025, use at your own risk;
theStuff ();
////////////////////////////////////
////// the main //////
function theStuff () {
if (documents.length > 0) {
var originalRulerUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
var myDocument = activeDocument;
var theGuides = getGuides();
if (theGuides[1].length < 3) {alert ("do it properly");
return};
if (hasLayerMask () == false) {addLayerMask()}
else {selectLayerMask ()};
////////////////////////////////////
addGradient([0, theGuides[1][theGuides[1].length-2]], [0, theGuides[1][theGuides[1].length-3]]);
////////////////////////////////////
app.preferences.rulerUnits = originalRulerUnits;
}
};
////// add layer mask //////
function addLayerMask () {
var desc1221 = new ActionDescriptor();
var idchannel = stringIDToTypeID( "channel" );
desc1221.putClass( stringIDToTypeID( "new" ), idchannel );
var ref7 = new ActionReference();
ref7.putEnumerated( idchannel, idchannel, stringIDToTypeID( "mask" ) );
desc1221.putReference( stringIDToTypeID( "at" ), ref7 );
desc1221.putEnumerated( stringIDToTypeID( "using" ), stringIDToTypeID( "userMaskEnabled" ), stringIDToTypeID( "revealAll" ) );
executeAction( stringIDToTypeID( "make" ), desc1221, DialogModes.NO );
};
////// select layer mask //////
function selectLayerMask () { 
var desc237 = new ActionDescriptor();
var ref5 = new ActionReference();
ref5.putEnumerated( stringIDToTypeID( "channel" ), stringIDToTypeID( "channel" ), stringIDToTypeID( "mask" ) );
desc237.putReference( stringIDToTypeID( "null" ), ref5 );
desc237.putBoolean( stringIDToTypeID( "makeVisible" ), true );
executeAction( stringIDToTypeID( "select" ), desc237, DialogModes.NO );
};
////// has layer mask //////
function hasLayerMask () {  
var m_Dsc01, m_Ref01;
m_Ref01 = new ActionReference();
m_Ref01.putEnumerated(stringIDToTypeID("layer"), charIDToTypeID("Ordn"), charIDToTypeID("Trgt"));
m_Dsc01 = executeActionGet(m_Ref01);
return m_Dsc01.hasKey(charIDToTypeID("Usrs"));
};
//////
function addGradient (x1, x2) {
var idhorizontal = stringIDToTypeID( "horizontal" );
var idvertical = stringIDToTypeID( "vertical" );
var idpixelsUnit = stringIDToTypeID( "pixelsUnit" );
var idgradientForm = stringIDToTypeID( "gradientForm" );
var idlocation = stringIDToTypeID( "location" );
var idmidpoint = stringIDToTypeID( "midpoint" );
var idtransferSpec = stringIDToTypeID( "transferSpec" );
var idgradientClassEvent = stringIDToTypeID( "gradientClassEvent" );
// =======================================================
    var desc1222 = new ActionDescriptor();
        var desc1223 = new ActionDescriptor();
        desc1223.putUnitDouble( idhorizontal, idpixelsUnit, x1[0] );
        desc1223.putUnitDouble( idvertical, idpixelsUnit, x1[1] );
    desc1222.putObject( stringIDToTypeID( "from" ), stringIDToTypeID( "paint" ), desc1223 );
        var desc1224 = new ActionDescriptor();
        desc1224.putUnitDouble( idhorizontal, idpixelsUnit, x2[0] );
        desc1224.putUnitDouble( idvertical, idpixelsUnit, x2[1] );
    desc1222.putObject( stringIDToTypeID( "to" ), stringIDToTypeID( "paint" ), desc1224 );
    desc1222.putEnumerated( stringIDToTypeID( "type" ), stringIDToTypeID( "gradientType" ), stringIDToTypeID( "linear" ) );
    desc1222.putBoolean( stringIDToTypeID( "dither" ), true );
    desc1222.putBoolean( stringIDToTypeID( "useMask" ), true );
    desc1222.putEnumerated( stringIDToTypeID( "gradientsInterpolationMethod" ), stringIDToTypeID( "gradientInterpolationMethodType" ), stringIDToTypeID( "linear" ) );
    var idgradient = stringIDToTypeID( "gradient" );
        var desc1225 = new ActionDescriptor();
        var idname = stringIDToTypeID( "name" );
        desc1225.putString( idname, "Black to White");
        //desc1225.putString( idname, "Foreground to Background" );
        desc1225.putEnumerated( idgradientForm, idgradientForm, stringIDToTypeID( "customStops" ) );
        var idinterfaceIconFrameDimmed = stringIDToTypeID( "interfaceIconFrameDimmed" );
        desc1225.putDouble( idinterfaceIconFrameDimmed, 4096.000000 );
            var list241 = new ActionList();
                var desc1226 = new ActionDescriptor();
                    var desc1227 = new ActionDescriptor();
                    desc1227.putDouble( stringIDToTypeID( "gray" ), 0.000000 );
                desc1226.putObject( stringIDToTypeID( "color" ), stringIDToTypeID( "grayscale" ), desc1227 );
                desc1226.putEnumerated( stringIDToTypeID( "type" ), stringIDToTypeID( "colorStopType" ), stringIDToTypeID( "userStop" ) );
                desc1226.putInteger( stringIDToTypeID( "location" ), 0 );
                desc1226.putInteger( stringIDToTypeID( "midpoint" ), 50 );
            list241.putObject( stringIDToTypeID( "colorStop" ), desc1226 );
                var desc1228 = new ActionDescriptor();
                    var desc1229 = new ActionDescriptor();
                    desc1229.putDouble( stringIDToTypeID( "gray" ), 100.000000 );
                var idgrayscale = stringIDToTypeID( "grayscale" );
                desc1228.putObject( stringIDToTypeID( "color" ), idgrayscale, desc1229 );
                desc1228.putEnumerated( stringIDToTypeID( "type" ), stringIDToTypeID( "colorStopType" ), stringIDToTypeID( "userStop" ) );
                desc1228.putInteger( stringIDToTypeID( "location" ), 4096 );
                desc1228.putInteger( stringIDToTypeID( "midpoint" ), 50 );
            list241.putObject( stringIDToTypeID( "colorStop" ), desc1228 );
        desc1225.putList( stringIDToTypeID( "colors" ), list241 );
            var list242 = new ActionList();
                var desc1230 = new ActionDescriptor();
                desc1230.putUnitDouble( stringIDToTypeID( "opacity" ), stringIDToTypeID( "percentUnit" ), 100.000000 );
                desc1230.putInteger( idlocation, 0 );
                desc1230.putInteger( idmidpoint, 50 );
            list242.putObject( idtransferSpec, desc1230 );
                var desc1231 = new ActionDescriptor();
                desc1231.putUnitDouble( stringIDToTypeID( "opacity" ), stringIDToTypeID( "percentUnit" ), 100.000000 );
                desc1231.putInteger( idlocation, 4096 );
                desc1231.putInteger( idmidpoint, 50 );
            list242.putObject( idtransferSpec, desc1231 );
        desc1225.putList( stringIDToTypeID( "transparency" ), list242 );
    desc1222.putObject( idgradient, idgradientClassEvent, desc1225 );
executeAction( idgradientClassEvent, desc1222, DialogModes.NO );
};
////// get guides //////
function getGuides () {
// set to pixels;
var myDocument = app.activeDocument;
var originalRulerUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// collect guides;
var theVerticalArray = new Array;
var theHorizontalArray = new Array;
for (var m = 0; m < myDocument.guides.length; m++) {
if (myDocument.guides[m].direction == Direction.HORIZONTAL) {theHorizontalArray.push(Number(myDocument.guides[m].coordinate))}
else {theVerticalArray.push(Number(myDocument.guides[m].coordinate))}
};
theHorizontalArray.sort(sortByDate);
theVerticalArray.sort(sortByDate);
app.preferences.rulerUnits = originalRulerUnits;
return [theVerticalArray, theHorizontalArray];
function sortByDate(a,b) {
if (Number(a)<Number(b)) return -1;
if (Number(a)>Number(b)) return 1;
return 0;
};
};

[marcin_1620]

Hi, c.pfaffenbichler, thank you very much for your help. Your code works for me and does exactly what I need. I’m not very good with scripting, so this helped a lot. Thanks again for your time!

[c.pfaffenbichler]

You’re welcome. 

If you should ever want to delve into Scripting more deeply you might want to focus on UXP Scripting right away – »ESTK Scripting« is on legacy status and the functionality might be removed from Photoshop altogether sometime in the future. 

[marcin_1620]

Thanks for the info! I will check UXP scripting. I use script a lot, so I’m a bit worried something may stop working in the future. Thanks again!